
eBPFプログラム用のRust仮想マシンおよびJITコンパイラ
eBPF 用の Rust(ユーザー空間)仮想マシン
このクレートには、eBPF プログラムを実行するための仮想マシンが含まれています。BPF とは Berkeley Packet Filter のことで、もともと BSD システム向けに開発されたアセンブリ風の言語であり、 tcpdump などのツールを用いてカーネル内でパケットをフィルタリングし、ユーザー空間への無駄なコピーを 避けるために作られました。その後 Linux に移植され、より高速で多機能な eBPF(extended BPF)へと 進化しました。BPF プログラムは本来カーネル内で実行されることを想定していますが、このクレートの 仮想マシンはそれをユーザー空間のアプリケーションで実行できるようにします。インタプリタ、 eBPF プログラム用の x86_64 JIT コンパイラ、そして逆アセンブラを含んでいます。
これは Rich Lane による uBPF ソフトウェア を基にしており、 ほぼ同じ機能を持ちますが、C で書かれています。
このクレートは Linux、MacOS X、Windows でコンパイルおよび実行できるはずですが、 現時点では JIT コンパイラは Windows では動作しません。
このクレートは crates.io から入手可能であり、
Cargo.toml ファイルに依存関係として追加するだけでそのまま動作するはずです:
[dependencies]
rbpf = "0.4.2"
開発版はこの GitHub リポジトリからも利用できます。これは、以下を Cargo.toml に記述するだけで簡単に使えます:
[dependencies]
rbpf = { git = "https://github.com/qmonnet/rbpf" }
もちろん、必要であればローカルにクローンして、クレートを改変し、Cargo.toml でローカルバージョンのパスを指定することもできます:
[dependencies]
rbpf = { path = "path/to/rbpf" }
次に、ソースコード内でそのクレートを使用することを指定します:
extern crate rbpf;
APIはソースコード内でかなり詳しく文書化されています。また、こちらのドキュメントのオンライン版にもアクセスできるはずです。これはcrates.ioのバージョンから自動生成されたものであり(mainブランチと同期していない可能性があります)。Examplesとunit testsも役立つはずです。以下にこのクレートの使用方法の概要を示します。
rbpfでeBPFプログラムを実行するために従うべき手順は次のとおりです:
eBPFは当初、パケットをフィルタリングするために設計されました(現在ではLinuxカーネル内にkprobesなど他のフックもありますが、これはrbpfではカバーされていません)。その結果、プログラムのロード命令とストア命令のほとんどは、パケットデータを表すメモリ領域に対して実行されます。しかし、Linuxカーネルでは、eBPFプログラムはこのデータ領域に直接アクセスしません:最初は、代わりにCのstruct sk_buffにアクセスでき、これはパケットに関するメタデータ(パケットデータ領域の先頭と末尾のメモリアドレスを含む)を含むバッファです。したがって、プログラムはまずこれらのポインタをsk_buffからロードし、その後パケットデータにアクセスできます。
この動作はrbpfで再現できますが、必須ではありません。このため、さまざまな種類の仮想マシンを表すいくつかの構造体があります:
struct EbpfVmMbufferはカーネルを模倣します。プログラムが実行されると、最初のeBPFレジスタに提供されるアドレスは、ユーザーが提供するメタデータバッファのアドレスとなり、そのバッファにはパケットデータメモリ領域の先頭と末尾へのポインタが含まれていることが期待されます。
struct EbpfVmFixedMbuffには1つの目的があります:カーネルと互換性を持つように作成されたプログラムの実行を可能にしつつ、ユーザーがメタデータバッファを手動で扱う手間を省くことです。実際、この構造体はプログラムに渡される静的な内部バッファを持っています。ユーザーは、eBPFプログラムがバッファ内のパケットデータの先頭と末尾を見つけることを期待するオフセット値を指定する必要があります。プログラムを実行する関数(JITされたかどうかに関わらず)を呼び出すと、この構造体は、プログラムが呼び出されたパケットデータの先頭と末尾について、指定されたオフセットでこの静的バッファ内のアドレスを自動的に更新します。
struct EbpfVmRawは、パケットデータ上で直接実行したいプログラム向けです。メタデータバッファは関与せず、eBPFプログラムは最初のレジスタでパケットデータのアドレスを直接受け取ります。これはuBPFの動作です。
struct EbpfVmNoDataはデータを一切取りません。eBPFプログラムは引数を一切取らず、その戻り値は決定的です。これに有効なユースケースがあるかは定かではありませんが、少なくともユニットテストには非常に便利です。
これらの構造体はすべて、同じパブリック関数を実装しています:
// called with EbpfVmMbuff:: prefix
pub fn new(prog: &'a [u8]) -> Result<EbpfVmMbuff<'a>, Error>
// called with EbpfVmFixedMbuff:: prefix
pub fn new(prog: &'a [u8],
data_offset: usize,
data_end_offset: usize) -> Result<EbpfVmFixedMbuff<'a>, Error>
// called with EbpfVmRaw:: prefix
pub fn new(prog: &'a [u8]) -> Result<EbpfVmRaw<'a>, Error>
// called with EbpfVmNoData:: prefix
pub fn new(prog: &'a [u8]) -> Result<EbpfVmNoData<'a>, Error>
これはVMの新しいインスタンスを作成するために使用されます。戻り値の型は、関数が呼び出された構造体に依存します。例えば、rbpf::EbpfVmRaw::new(Some(my_program)) は struct rbpf::EbpfVmRaw のインスタンスを返します(Result でラップされています)。プログラムがロードされると、非常にシンプルな検証器(Linuxカーネルのものとは程遠い)でチェックされます。ユーザーはこれをカスタム検証器に置き換えることもできます。
struct EbpfVmFixedMbuff の場合、コンストラクタに2つの追加引数を渡す必要があります:data_offset と data_end_offset です。これらは、プログラムが実行されるたびに、パケットデータのメモリ領域の先頭と末尾へのポインタが内部メタデータバッファにそれぞれ格納されるオフセット(バイト数)です。他の構造体はこのメカニズムを使用しないため、これらのオフセットは必要ありません。
// for struct EbpfVmMbuff, struct EbpfVmRaw and struct EbpfVmRawData
pub fn set_program(&mut self, prog: &'a [u8]) -> Result<(), Error>
// for struct EbpfVmFixedMbuff
pub fn set_program(&mut self, prog: &'a [u8],
data_offset: usize,
data_end_offset: usize) -> Result<(), Error>
例えば my_vm.set_program(my_program); を使用すると、VM インスタンスの作成後にロードされたプログラムを変更できます。このプログラムは、VM にアタッチされた検証器によってチェックされます。VM の検証関数はいつでも変更できます。
pub type Verifier = fn(prog: &[u8]) -> Result<(), Error>;
pub fn set_verifier(&mut self,
verifier: Verifier) -> Result<(), Error>
プログラムがすでにVMにロードされている場合、新しいverifierを設定すると、ロード済みのプログラムに対して即座に実行されることに注意してください。ただし、プログラムがロードされていない場合(VM作成時にnew()メソッドへNoneを渡した場合)は、verifierは実行されません。
pub type Helper = fn (u64, u64, u64, u64, u64) -> u64;
pub fn register_helper(&mut self,
key: u32,
function: Helper) -> Result<(), Error>
この関数はヘルパー関数を登録するために使用されます。VMはレジスタをハッシュマップに格納するため、キーには任意のu32値を使用できます。これは、Linuxカーネルと互換性を持つ必要があり、したがって特定のヘルパー番号を使用しなければならないプログラムに役立つ場合があります。
pub fn register_allowed_memory(&mut self, addrs_range: Range<u64>) -> ()
この関数は、eBPFプログラムがロードおよびストアを許可されるメモリアドレスのリストを追加します。この関数を複数回呼び出すと、アドレスが内部のHashSetに追加されます。現時点では、rbpfはインタプリタを使用する場合にのみメモリアクセスを検証します。この関数は、eBPFマップに格納されたオブジェクトへのポインタを返すカーネルヘルパーを使用する場合に有用です。
// for struct EbpfVmMbuff
pub fn execute_program(&self,
mem: &'a mut [u8],
mbuff: &'a mut [u8]) -> Result<(u64), Error>
// for struct EbpfVmFixedMbuff and struct EbpfVmRaw
pub fn execute_program(&self,
mem: &'a mut [u8]) -> Result<(u64), Error>
// for struct EbpfVmNoData
pub fn execute_program(&self) -> Result<(u64), Error>
読み込まれたプログラムを解釈します。この関数は、使用するVMの種類に応じて、パケットデータとメタデータバッファへの参照、パケットデータのみへの参照、または何も受け取りません。返される値はeBPFプログラムの結果です。
pub fn jit_compile(&mut self) -> Result<(), Error>
読み込まれたプログラムを x86_64 アーキテクチャ向けに JIT コンパイルします。プログラムがヘルパー関数を使用する場合、この関数が呼び出される前にそれらを VM に登録する必要があります。生成されたアセンブリ関数は VM の内部に保存されます。
// for struct EbpfVmMbuff
pub unsafe fn execute_program_jit(&self, mem: &'a mut [u8],
mbuff: &'a mut [u8]) -> Result<(u64), Error>
// for struct EbpfVmFixedMbuff and struct EbpfVmRaw
pub unsafe fn execute_program_jit(&self, mem: &'a mut [u8]) -> Result<(u64), Error>
// for struct EbpfVmNoData
pub unsafe fn execute_program_jit(&self) -> Result<(u64), Error>
JITコンパイルされたプログラムを呼び出します。指定する引数は execute_program() の場合と同じで、これも使用するVMの種類によって異なります。JITコンパイルされたプログラムの結果はインタプリタの場合と同じになるはずですが、より高速に実行されるはずです。プログラム実行中にエラーが発生した場合、JITコンパイル版はインタプリタほど適切に処理できず、プログラムがクラッシュする可能性があることに注意してください。このため、これらの関数は unsafe としてマークされています。
これはユニットテスト test_vm_add からのものです。
extern crate rbpf;
fn main() {