mirror of
https://github.com/michael-yuji/xc.git
synced 2025-12-11 17:29:43 +01:00
Update README.md
This commit is contained in:
elliptic-kitty
GitHub
139
README.md
139
README.md
@@ -1,25 +1,142 @@
|
||||
# xc
|
||||
##### This README last updated on 31st March, 2024
|
||||
|
||||
##### This README last updated on 24th September, 2023
|
||||
xc is a work-in-progress container engine for FreeBSD that is capable to run FreeBSD containers and Linux (Docker) containers. Unlike `podman`, this project is intend to be more FreeBSD focused and made adjustment to support and integrate with FreeBSD specific features, such as `Pf`, `ZFS`, `DTrace` and `Jail`(including nested jails/containers and VNET/Non-VNET networking).
|
||||
|
||||
xc is a work-in-progress container engine for FreeBSD. This README document is intended for contributors, developers or anyone curious about this project to understand, build, run and contribute. This is not a step-by-step documentation, and such documentation (although is work-in-progress and potentially a bit outdated compare to the main branch) can be found [here](https://hackmd.io/7BIT_khIRQyPAe4EdiigHg)
|
||||
Please scroll to [Quick Start](#quick-start) session for usage. To under start `xc` a bit more and how everything is put together, please jump to [In-depth documentation](#in-depth-documentation) session.
|
||||
|
||||
A more detailed (but bit outdated) documentation can be found [here](https://hackmd.io/7BIT_khIRQyPAe4EdiigHg)
|
||||
|
||||
## Overview
|
||||
# Quick Start
|
||||
|
||||
`xc` consists of 3 binaries, `xc` (client), `xcd` (server), `ocitar` (OCI layer archive helper). `xcd` depends on `ocitar` to run correctly, hence `ocitar` should exists in under one of `xcd`'s `$PATH` directories.
|
||||
This session covers how to use [xc](https://github.com/michael-yuji/xc), the FreeBSD container engine.
|
||||
|
||||
All three binaries can be built simply by runnig `cargo build` in the source directory.
|
||||
`xc` is not yet available as a port, so you'll have to build and install by yourself. Luckily, the process is easy.
|
||||
|
||||
#### Build Requirement
|
||||
## Requirement:
|
||||
- FreeBSD 14 (amd64 or arm64)
|
||||
- ZFS
|
||||
- Enable pf
|
||||
|
||||
- FreeBSD 13 stable or newer (tested on both arm64 and amd64)
|
||||
- cargo (require nightly if intended to build USDT probes for `xcd`)
|
||||
- cmake (sqlite build dependency)
|
||||
## Build and install
|
||||
Run the following commands. If you prefer `doas` over `sudo`, feel free to use it.
|
||||
```shell
|
||||
sudo pkg install git cmake rust
|
||||
git clone https://github.com/michael-yuji/xc.git
|
||||
cd xc && cargo build --release
|
||||
sudo cp target/release/xcd /usr/local/sbin
|
||||
sudo cp target/release/{ocitar, xc} /usr/local/bin
|
||||
```
|
||||
|
||||
## Configuration
|
||||
Before configuring `xc`. Give the following questions a thought:
|
||||
- which network interface should serve as the external interface for your containers
|
||||
- in which ZFS pool/dataset you wish the data lives in
|
||||
|
||||
## Installation
|
||||
Copy `xc`, `ocitar`, and `xcd` to one of the `$PATH` directories from build directories (`$src/target/release` for release build, `$src/target/debug` for debug build)
|
||||
Assume the answer of your first question in `em0`, and for the second question `zroot/xc`, create a yaml file at `/usr/local/etc/xc.conf`.
|
||||
|
||||
```yaml
|
||||
# for published ports, for example `-p 80:8080`, only packets reaching
|
||||
# the `ext_ifs` forwards to the container(s) by default
|
||||
ext_ifs:
|
||||
- em0
|
||||
|
||||
# dataset to store the container images, each image becomes a child dataset
|
||||
image_dataset: zroot/xc/datasets
|
||||
|
||||
# dataset contains the root of running containers
|
||||
container_dataset: zroot/xc/run
|
||||
|
||||
# dataset serving volumes
|
||||
default_volume_dataset: zroot/xc/volumes
|
||||
```
|
||||
|
||||
### Make network accessible
|
||||
|
||||
Part of the core value of `xc` is to bring operator no surprise, hence it is not going to configure networking/firewall setting for you automatically.
|
||||
|
||||
Instead, `xc` creates entries, allocate and set ip addresses, insert forwarding rules to anchors you provides explicitly. Therefore, we need to add some rules to our pf configuartion to forward packets.
|
||||
|
||||
First, ensure that the host can forward packets. To make the following command preserve across reboots, add `gateway_enable="YES"` to `rc.conf`.
|
||||
|
||||
`sysctl net.inet.ip.forwarding=1`
|
||||
|
||||
Now, create following to `pf.conf`. We are assuming to use `em0` to serve internet traffic for our containers.
|
||||
|
||||
```
|
||||
ext_if="em0"
|
||||
nat on $ext_if from <xc:network:default> to any -> ($ext_if)
|
||||
rdr-anchor xc-rdr
|
||||
```
|
||||
|
||||
You may have notice the pf table `<xc:network:default>`. We are going to create an xc network named `default` later. Whenever a container request an address from this network, `xc` insert the address to this table such that the `nat` rule will work.
|
||||
|
||||
Similarly, `xc` insert its port forwarding rules to `xc-rdr`. loading this anchor causes the forwarding rules created by `xc` to work.
|
||||
|
||||
### Creating network interface
|
||||
|
||||
```shell
|
||||
ifconfig bridge create name xc0
|
||||
ifconfig xc0 172.16.0.254/24 up
|
||||
```
|
||||
|
||||
As mentioned before, `xc` never invade your network without your explicit setup, instead you tell `xc` where you want the containers' connectivities should go. We are going to create the `default` network later, and all containers using the `default` network will either create an alias on this interface (if it's a non-VNET container), or create a `epair` interface and add as a member to this bridge.
|
||||
|
||||
## Starting up
|
||||
|
||||
In a different terminal, or in a tmux session, start `xcd` as root.
|
||||
`sudo xcd`
|
||||
|
||||
### Creating our first network
|
||||
As mentioned in the previous session, we are going to create our first network for our containers. Let's call it `default`.
|
||||
|
||||
`xc create network --alias xc0 --bridge xc0 --default-router 172.16.0.254 default 172.16.0.0/24`
|
||||
|
||||
This tells xc to create a network that
|
||||
- named `default`
|
||||
- with address pool of `172.16.0.0/24`, `xc` can automatically allocate address from this pool if an explicit address is not specified
|
||||
- when create a non-VNET jail, create the IP alias on `xc0`
|
||||
- when create a VNET jail, bridge the `epair` interface to `xc0`
|
||||
|
||||
### Create our first FreeBSD container
|
||||
|
||||
First pull the container image
|
||||
```
|
||||
xc pull freebsdxc/freebsd:13.2
|
||||
```
|
||||
Now run the container. A network-less container is useless, so let's make it a VNET jail (`--vnet`) and attach to the network we created earlier, `default`:
|
||||
```
|
||||
xc run -it --vnet --network default -- /bin/sh
|
||||
```
|
||||
|
||||
Now you have your very first container to play with.
|
||||
|
||||
### Using Linux containers from DockerHub
|
||||
|
||||
`xc` can run Linux containers via FreeBSD Linuxulator.
|
||||
|
||||
First you need to configure your host to support that, that includes loading the required kernel modules and a sysctl to make the kernel run unknown ELF binary as Linux binaries (go binaries does that).
|
||||
|
||||
Load the following kernel modules: `kldload linux64 linprocfs linsysfs`
|
||||
|
||||
You may want to run `kldload linux` as well to run i386 Linux containers.
|
||||
|
||||
Modify the sysctl: `kern.elf64.fallback_brand=3`
|
||||
|
||||
#### Try!
|
||||
|
||||
Pull the Linux mariadb 10.9 image from dockerhub:
|
||||
```shell
|
||||
xc pull library/mariadb:10.9
|
||||
```
|
||||
|
||||
Run it:
|
||||
```shell
|
||||
xc run -e MARIADB_ROOT_PASSWORD=password library/mariadb:10.9
|
||||
```
|
||||
|
||||
# In-Depth documentation
|
||||
🚧 under construction and refinement 🚧
|
||||
|
||||
## Configuration
|
||||
`xc` now take yaml configuration. The scheme (`struct XcConfig`) for the configuration file can be found at `xcd/src/config/mod.rs`. By default, `xcd` looks for the configuration at `/usr/local/etc/xc.config`
|
||||
|
||||
Reference in New Issue
Block a user