delphix/zfs-builder repository overview

⁠Docker ZFS Builder

This image is designed to build ZFS on Linux for any kernel, even those that are different from the one running on the host system. To build the latest ZFS for the currently running system, run:

$ docker run -v /:/build delphix/zfs-builder:latest

If you are running CentOS, and are not providing a centos-release config file, you will need to launch the container in privileged mode in order to access the host filesystem, add --privileged --pid=host.

If you are performing a LinuxKit or CentOS build, you will need to provide access to launch docker containers, add -v /var/run/docker.sock:/var/run/docker.sock.

To configure the container to buld for a kernel other than the running system, the following configuration options are available:

• -e ZFS_VERSION=zfs-0.8.0 - Version of ZFS to build. Must correspond to a tag or a commit hash in the zfsonlinux/zfs github repository. Defaults to the latest tag.
• -e KERNEL_RELEASE=4.9.125-linuxkit - Version of the kernel interfaces to use, from uname -r.
• -e KERNEL_UNAME=... - Complete uname -a output identifying the kernel.
• -v path:/build - Output where ZFS binaries (kernel modules and userland tools) will be placed, using their absolute path (e.g. /build/sbin/zfs)
• -v path:/config - Additional OS-specific content required to build.

⁠Supported OSes

For building userland ZFS, any OS is supported. For kernel ZFS, the build system supports the following operating systems:

• Ubuntu - Does not require any additional configuration. Tested with bionic, may or may not work for other releases.
• LinuxKit - Requires access to the docker socket. Tested with 4.9.125 and later, may or may not work with other releases.
• CentOS - Requires access to the docker socket, and either (a) privileged host access or (b) /config/centos-release from /etc/centos-release. Tested with CentOS 7, may or may not work with other releases.
• Vanilla - Requires either (a) /proc/config.gz to be present, or /config/config.gz to be present with the kernel configuration. Optionally can specify the kernel source with -v path:/src/linux, otherwise source will be downloaded from kernel.org.

If the system isn't recognized, it will try to download and build the vanilla kernel source that matches the given version, but (a) this will take a long time and (b) we may or may not have the right patches and modifications in place to build the correct version. YMMV, and no guarantees are made that the resulting kernel binaries will work.

If you'd like to add support for a new OS, you can look at the different models employed by Ubuntu (native download and build within container), LinuxKit (download source via container, build locally), and CentOS (download and build entirely within container) for different models.

⁠Additional configuration

While not the primary configuration parameters, the following options can also be used:

• -v path:/src/zfs - Specify the ZFS source to use. If this is present, then the builder will skip cloning and checking out the ZFS source, and use what's here instead. ZFS_VERSION is ignored in this case.
• -e ZFS_CONFIG=all|user|kernel - Control what ZFS binaries to build, defaults to all. If user is specified, then the kernel build steps are skipped.

This builder only works with ZFS version 0.8.0 or later, as the spl repository has been merged and no longer needs to be built separately.

⁠How it works

ZFS, like other kernel modules, has a dependency on the interfaces of the running kernel. Normally, this is built against the currently running kernel. But this creates challenges for users to always install all the requisite build tools and find the requisite kernel source, not to mention cases where you might want to build packages for a kernel other than the one you are currently running (such as part of an automated process using standard build machines).

To accomplish this, the ZFS builder does the following:

1. Clone https://github.com/zfsonlinux/zfs.git into /src/zfs and checks out the appropriate tag (unless /src/zfs already exists)
2. Build the kernel, if necessary. First check the kernel release variant and, if a known distro, download pre-built kernel headers, objects, and/or source through distro-specific means. Otherwise get the source from www.kernel.org and build it by hand.
3. Build /src/zfs
4. Copy the resulting binaries to /build

⁠Contribute

1. Fork the project.
2. Make your bug fix or new feature.
3. Add tests for your code.
4. Send a pull request.

Contributions must be signed as User Name <[email protected]>. Make sure to set up Git with user name and email address⁠. All development should be done on the master branch.

⁠Code of Conduct

This project operates under the Delphix Code of Conduct⁠. By participating in this project you agree to abide by its terms.

⁠Contributor Agreement

All contributors are required to sign the Delphix Contributor agreement prior to contributing code to an open source repository. This process is handled automatically by cla-assistant⁠. Simply open a pull request and a bot will automatically check to see if you have signed the latest agreement. If not, you will be prompted to do so as part of the pull request process.

⁠Reporting Issues

Issues should be reported here⁠.

⁠Statement of Support

This software is provided as-is, without warranty of any kind or commercial support through Delphix. See the associated license for additional details. Questions, issues, feature requests, and contributions should be directed to the community as outlined in the Delphix Community Guidelines⁠.

⁠License

This is code is licensed under the Apache License 2.0. Full license is available here⁠.