use std::io; use std::mem::size_of; use std::os::unix::io::AsRawFd; use std::os::unix::io::BorrowedFd; use crate::Error; use crate::Result; /// See [`libbpf_sys::bpf_tc_attach_point`]. pub type TcAttachPoint = libbpf_sys::bpf_tc_attach_point; /// See [`libbpf_sys::BPF_TC_INGRESS`]. pub const TC_INGRESS: TcAttachPoint = libbpf_sys::BPF_TC_INGRESS; /// See [`libbpf_sys::BPF_TC_EGRESS`]. pub const TC_EGRESS: TcAttachPoint = libbpf_sys::BPF_TC_EGRESS; /// See [`libbpf_sys::BPF_TC_CUSTOM`]. pub const TC_CUSTOM: TcAttachPoint = libbpf_sys::BPF_TC_CUSTOM; pub type TcFlags = libbpf_sys::bpf_tc_flags; /// See [`libbpf_sys::BPF_TC_F_REPLACE`]. pub const BPF_TC_F_REPLACE: TcFlags = libbpf_sys::BPF_TC_F_REPLACE; // from kernel @ include/uapi/linux/pkt_sched.h #[allow(missing_docs)] pub const TC_H_INGRESS: u32 = 0xFFFFFFF1; #[allow(missing_docs)] pub const TC_H_CLSACT: u32 = TC_H_INGRESS; #[allow(missing_docs)] pub const TC_H_MIN_INGRESS: u32 = 0xFFF2; #[allow(missing_docs)] pub const TC_H_MIN_EGRESS: u32 = 0xFFF3; #[allow(missing_docs)] pub const TC_H_MAJ_MASK: u32 = 0xFFFF0000; #[allow(missing_docs)] pub const TC_H_MIN_MASK: u32 = 0x0000FFFF; /// Represents a location where a TC-BPF filter can be attached. /// /// The BPF TC subsystem has different control paths from other BPF programs. /// As such a BPF program using a TC Hook (`SEC("classifier")` or `SEC("tc")`) must be operated /// more independently from other [`Program`][crate::Program]s. /// /// This struct exposes operations to create, attach, query and destroy /// a bpf_tc_hook using the TC subsystem. /// /// Documentation about the libbpf TC interface can be found /// [here](https://lwn.net/ml/bpf/20210512103451.989420-3-memxor@gmail.com/). /// /// An example of using a BPF TC program can found /// [here](https://github.com/libbpf/libbpf-rs/tree/master/examples/tc_port_whitelist). #[derive(Clone, Copy, Debug)] pub struct TcHook { hook: libbpf_sys::bpf_tc_hook, opts: libbpf_sys::bpf_tc_opts, } impl TcHook { /// Create a new [`TcHook`] given the file descriptor of the loaded /// `SEC("tc")` [`Program`][crate::Program]. pub fn new(fd: BorrowedFd<'_>) -> Self { let mut tc_hook = TcHook { hook: libbpf_sys::bpf_tc_hook::default(), opts: libbpf_sys::bpf_tc_opts::default(), }; tc_hook.hook.sz = size_of::() as libbpf_sys::size_t; tc_hook.opts.sz = size_of::() as libbpf_sys::size_t; tc_hook.opts.prog_fd = fd.as_raw_fd(); tc_hook } /// Create a new [`TcHook`] as well as the underlying qdiscs /// /// If a [`TcHook`] already exists with the same parameters as the hook calling /// [`Self::create()`], this function will still succeed. /// /// Will always fail on a `TC_CUSTOM` hook pub fn create(&mut self) -> Result { let err = unsafe { libbpf_sys::bpf_tc_hook_create(&mut self.hook as *mut _) }; if err != 0 { let err = io::Error::from_raw_os_error(-err); // the hook may already exist, this is not an error if err.kind() == io::ErrorKind::AlreadyExists { Ok(*self) } else { Err(Error::from(err)) } } else { Ok(*self) } } /// Set the interface to attach to /// /// Interfaces can be listed by using `ip link` command from the iproute2 software package pub fn ifindex(&mut self, idx: i32) -> &mut Self { self.hook.ifindex = idx; self } /// Set what type of TC point to attach onto /// /// `TC_EGRESS`, `TC_INGRESS`, or `TC_CUSTOM` /// /// An `TC_EGRESS|TC_INGRESS` hook can be used as an attach point for calling /// [`Self::destroy()`] to remove the clsact bpf tc qdisc, but cannot be used for an /// [`Self::attach()`] operation pub fn attach_point(&mut self, ap: TcAttachPoint) -> &mut Self { self.hook.attach_point = ap; self } /// Set the parent of a hook /// /// Will cause an EINVAL upon [`Self::attach()`] if set upon an /// `TC_EGRESS/TC_INGRESS/(TC_EGRESS|TC_INGRESS)` hook /// /// Must be set on a `TC_CUSTOM` hook /// /// Current acceptable values are `TC_H_CLSACT` for `maj`, and `TC_H_MIN_EGRESS` or /// `TC_H_MIN_INGRESS` for `min` pub fn parent(&mut self, maj: u32, min: u32) -> &mut Self { /* values from libbpf.h BPF_TC_PARENT() */ let parent = (maj & TC_H_MAJ_MASK) | (min & TC_H_MIN_MASK); self.hook.parent = parent; self } /// Set whether this hook should replace an existing hook /// /// If replace is not true upon attach, and a hook already exists /// an EEXIST error will be returned from [`Self::attach()`] pub fn replace(&mut self, replace: bool) -> &mut Self { if replace { self.opts.flags = BPF_TC_F_REPLACE; } else { self.opts.flags = 0; } self } /// Set the handle of a hook. /// If unset upon attach, the kernel will assign a handle for the hook pub fn handle(&mut self, handle: u32) -> &mut Self { self.opts.handle = handle; self } /// Get the handle of a hook. /// Only has meaning after hook is attached pub fn get_handle(&self) -> u32 { self.opts.handle } /// Set the priority of a hook /// If unset upon attach, the kernel will assign a priority for the hook pub fn priority(&mut self, priority: u32) -> &mut Self { self.opts.priority = priority; self } /// Get the priority of a hook /// Only has meaning after hook is attached pub fn get_priority(&self) -> u32 { self.opts.priority } /// Query a hook to inspect the program identifier (prog_id) pub fn query(&mut self) -> Result { let mut opts = self.opts; opts.prog_id = 0; opts.prog_fd = 0; opts.flags = 0; let err = unsafe { libbpf_sys::bpf_tc_query(&self.hook as *const _, &mut opts as *mut _) }; if err != 0 { Err(Error::from(io::Error::last_os_error())) } else { Ok(opts.prog_id) } } /// Attach a filter to the TcHook so that the program starts processing /// /// Once the hook is processing, changing the values will have no effect unless the hook is /// [`Self::attach()`]'d again (`replace=true` being required) /// /// Users can create a second hook by changing the handle, the priority or the attach_point and /// calling the [`Self::attach()`] method again. Beware doing this. It might be better to /// Copy the TcHook and change the values on the copied hook for easier [`Self::detach()`] /// /// NOTE: Once a [`TcHook`] is attached, it, and the maps it uses, will outlive the userspace /// application that spawned them Make sure to detach if this is not desired pub fn attach(&mut self) -> Result { self.opts.prog_id = 0; let err = unsafe { libbpf_sys::bpf_tc_attach(&self.hook as *const _, &mut self.opts as *mut _) }; if err != 0 { Err(Error::from(io::Error::last_os_error())) } else { Ok(*self) } } /// Detach a filter from a [`TcHook`] pub fn detach(&mut self) -> Result<()> { let mut opts = self.opts; opts.prog_id = 0; opts.prog_fd = 0; opts.flags = 0; let err = unsafe { libbpf_sys::bpf_tc_detach(&self.hook as *const _, &opts as *const _) }; if err != 0 { Err(Error::from_raw_os_error(-err)) } else { self.opts.prog_id = 0; Ok(()) } } /// Destroy attached filters /// /// If called on a hook with an attach_point of `TC_EGRESS`, will detach all egress hooks /// /// If called on a hook with an attach_point of `TC_INGRESS`, will detach all ingress hooks /// /// If called on a hook with an attach_point of `TC_EGRESS|TC_INGRESS`, will destroy the clsact /// tc qdisc and detach all hooks /// /// Will error with EOPNOTSUPP if attach_point is `TC_CUSTOM` /// /// It is good practice to query before destroying as the tc qdisc may be used by multiple /// programs pub fn destroy(&mut self) -> Result<()> { let err = unsafe { libbpf_sys::bpf_tc_hook_destroy(&mut self.hook as *mut _) }; if err != 0 { Err(Error::from_raw_os_error(-err)) } else { Ok(()) } } } /// Builds [`TcHook`] instances. /// /// [`TcHookBuilder`] is a way to ergonomically create multiple `TcHook`s, /// all with similar initial values. /// /// Once a `TcHook` is created via the [`Self::hook()`] method, the `TcHook`'s values can still /// be adjusted before [`TcHook::attach()`] is called. #[derive(Debug)] pub struct TcHookBuilder<'fd> { fd: BorrowedFd<'fd>, ifindex: i32, parent_maj: u32, parent_min: u32, replace: bool, handle: u32, priority: u32, } impl<'fd> TcHookBuilder<'fd> { /// Create a new `TcHookBuilder` with fd /// this fd should come from a loaded [`Program`][crate::Program] pub fn new(fd: BorrowedFd<'fd>) -> Self { TcHookBuilder { fd, ifindex: 0, parent_maj: 0, parent_min: 0, replace: false, handle: 0, priority: 0, } } /// Set the initial interface index to attach the hook on pub fn ifindex(&mut self, ifindex: i32) -> &mut Self { self.ifindex = ifindex; self } /// Set the initial parent of a hook pub fn parent(&mut self, maj: u32, min: u32) -> &mut Self { self.parent_maj = maj; self.parent_min = min; self } /// Set whether created hooks should replace existing hooks pub fn replace(&mut self, replace: bool) -> &mut Self { self.replace = replace; self } /// Set the initial handle for a hook pub fn handle(&mut self, handle: u32) -> &mut Self { self.handle = handle; self } /// Set the initial priority for a hook pub fn priority(&mut self, priority: u32) -> &mut Self { self.priority = priority; self } /// Create a [`TcHook`] given the values previously set /// /// Once a hook is created, the values can still be changed on the `TcHook` /// by calling the `TcHooks` setter methods pub fn hook(&self, attach_point: TcAttachPoint) -> TcHook { let mut hook = TcHook::new(self.fd); hook.ifindex(self.ifindex) .handle(self.handle) .priority(self.priority) .parent(self.parent_maj, self.parent_min) .replace(self.replace) .attach_point(attach_point); hook } }