diff options
| -rw-r--r-- | src/batch.rs | 13 | ||||
| -rw-r--r-- | src/chain.rs | 8 | ||||
| -rw-r--r-- | src/chain_methods.rs | 4 | ||||
| -rw-r--r-- | src/expr/bitwise.rs | 4 | ||||
| -rw-r--r-- | src/expr/cmp.rs | 13 | ||||
| -rw-r--r-- | src/expr/counter.rs | 2 | ||||
| -rw-r--r-- | src/expr/immediate.rs | 24 | ||||
| -rw-r--r-- | src/expr/log.rs | 4 | ||||
| -rw-r--r-- | src/expr/lookup.rs | 3 | ||||
| -rw-r--r-- | src/expr/meta.rs | 4 | ||||
| -rw-r--r-- | src/expr/mod.rs | 20 | ||||
| -rw-r--r-- | src/expr/nat.rs | 8 | ||||
| -rw-r--r-- | src/expr/payload.rs | 2 | ||||
| -rw-r--r-- | src/expr/register.rs | 4 | ||||
| -rw-r--r-- | src/expr/reject.rs | 7 | ||||
| -rw-r--r-- | src/expr/wrapper.rs | 2 | ||||
| -rw-r--r-- | src/lib.rs | 57 | ||||
| -rw-r--r-- | src/query.rs | 11 | ||||
| -rw-r--r-- | src/rule.rs | 14 | ||||
| -rw-r--r-- | src/rule_methods.rs | 33 | ||||
| -rw-r--r-- | src/table.rs | 6 |
21 files changed, 117 insertions, 126 deletions
diff --git a/src/batch.rs b/src/batch.rs index c8ec5aa..198e8d0 100644 --- a/src/batch.rs +++ b/src/batch.rs @@ -5,7 +5,7 @@ use std::os::raw::c_char; use std::ptr; use thiserror::Error; -/// Error while communicating with netlink +/// Error while communicating with netlink. #[derive(Error, Debug)] #[error("Error while communicating with netlink")] pub struct NetlinkError(()); @@ -67,9 +67,9 @@ impl Batch { self.next() } - /// Adds all the messages in the given iterator to this batch. If any message fails to be added - /// the error for that failure is returned and all messages up until that message stays added - /// to the batch. + /// Adds all the messages in the given iterator to this batch. If any message fails to be + /// added the error for that failure is returned and all messages up until that message stay + /// added to the batch. pub fn add_iter<T, I>(&mut self, msg_iter: I, msg_type: MsgType) where T: NlMsg, @@ -192,9 +192,8 @@ impl<'a> Iterator for Iter<'a> { } } -/// selected batch page is 256 Kbytes long to load ruleset of -/// half a million rules without hitting -EMSGSIZE due to large -/// iovec. +/// Selected batch page is 256 Kbytes long to load ruleset of half a million rules without hitting +/// -EMSGSIZE due to large iovec. pub fn default_batch_page_size() -> u32 { unsafe { libc::sysconf(libc::_SC_PAGESIZE) as u32 * 32 } } diff --git a/src/chain.rs b/src/chain.rs index 20043ac..a999b8d 100644 --- a/src/chain.rs +++ b/src/chain.rs @@ -101,7 +101,7 @@ impl Chain { Chain { chain, table } } - /// Sets the hook and priority for this chain. Without calling this method the chain well + /// Sets the hook and priority for this chain. Without calling this method the chain will /// become a "regular chain" without any hook and will thus not receive any traffic unless /// some rule forward packets to it via goto or jump verdicts. /// @@ -146,7 +146,7 @@ impl Chain { } } - /// Update the userdata of this chain. + /// Updates the userdata of this chain. pub fn set_userdata(&self, data: &CStr) { unsafe { sys::nftnl_chain_set_str(self.chain, sys::NFTNL_CHAIN_USERDATA as u16, data.as_ptr()); @@ -180,7 +180,7 @@ impl Chain { } } - /// Returns a reference to the [`Table`] this chain belongs to + /// Returns a reference to the [`Table`] this chain belongs to. /// /// [`Table`]: struct.Table.html pub fn get_table(&self) -> Rc<Table> { @@ -201,7 +201,7 @@ impl Chain { } impl fmt::Debug for Chain { - /// Return a string representation of the chain. + /// Returns a string representation of the chain. fn fmt(&self, fmt: &mut fmt::Formatter<'_>) -> fmt::Result { write!(fmt, "{:?}", self.get_str()) } diff --git a/src/chain_methods.rs b/src/chain_methods.rs index c41e085..d384c35 100644 --- a/src/chain_methods.rs +++ b/src/chain_methods.rs @@ -5,10 +5,10 @@ use std::rc::Rc; /// A helper trait over [`crate::Chain`]. pub trait ChainMethods { - /// Create a new Chain instance from a [`crate::Hook`] over a [`crate::Table`]. + /// Creates a new Chain instance from a [`crate::Hook`] over a [`crate::Table`]. fn from_hook(hook: Hook, table: Rc<Table>) -> Self where Self: std::marker::Sized; - /// Add a [`crate::Policy`] to the current Chain. + /// Adds a [`crate::Policy`] to the current Chain. fn verdict(self, policy: Policy) -> Self; fn add_to_batch(self, batch: &mut Batch) -> Self; } diff --git a/src/expr/bitwise.rs b/src/expr/bitwise.rs index 59ef41b..d34d22c 100644 --- a/src/expr/bitwise.rs +++ b/src/expr/bitwise.rs @@ -10,8 +10,8 @@ pub struct Bitwise<M: ToSlice, X: ToSlice> { } impl<M: ToSlice, X: ToSlice> Bitwise<M, X> { - /// Returns a new `Bitwise` instance that first masks the value it's applied to with `mask` - /// and then performs xor with the value in `xor`. + /// Returns a new `Bitwise` instance that first masks the value it's applied to with `mask` and + /// then performs xor with the value in `xor`. pub fn new(mask: M, xor: X) -> Self { Self { mask, xor } } diff --git a/src/expr/cmp.rs b/src/expr/cmp.rs index 384f0b4..f6ea900 100644 --- a/src/expr/cmp.rs +++ b/src/expr/cmp.rs @@ -101,11 +101,10 @@ impl<const N: usize> Expression for Cmp<[u8; N]> { Cmp::<u8>::get_raw_name() } - /// The raw data contained inside `Cmp` expressions can only be deserialized to - /// arrays of bytes, to ensure that the memory layout of retrieved data cannot be - /// violated. It is your responsibility to provide the correct length of the byte - /// data. If the data size is invalid, you will get the error - /// `DeserializationError::InvalidDataSize`. + /// The raw data contained inside `Cmp` expressions can only be deserialized to arrays of + /// bytes, to ensure that the memory layout of retrieved data cannot be violated. It is your + /// responsibility to provide the correct length of the byte data. If the data size is invalid, + /// you will get the error `DeserializationError::InvalidDataSize`. /// /// Example (warning, no error checking!): /// ```rust @@ -183,8 +182,8 @@ macro_rules! nft_expr_cmp { }; } -/// Can be used to compare the value loaded by [`Meta::IifName`] and [`Meta::OifName`]. Please -/// note that it is faster to check interface index than name. +/// Can be used to compare the value loaded by [`Meta::IifName`] and [`Meta::OifName`]. Please note +/// that it is faster to check interface index than name. /// /// [`Meta::IifName`]: enum.Meta.html#variant.IifName /// [`Meta::OifName`]: enum.Meta.html#variant.OifName diff --git a/src/expr/counter.rs b/src/expr/counter.rs index 71064df..4732e85 100644 --- a/src/expr/counter.rs +++ b/src/expr/counter.rs @@ -3,7 +3,7 @@ use crate::sys; use std::os::raw::c_char; /// A counter expression adds a counter to the rule that is incremented to count number of packets -/// and number of bytes for all packets that has matched the rule. +/// and number of bytes for all packets that have matched the rule. #[derive(Debug, PartialEq)] pub struct Counter { pub nb_bytes: u64, diff --git a/src/expr/immediate.rs b/src/expr/immediate.rs index 0787e06..71453b3 100644 --- a/src/expr/immediate.rs +++ b/src/expr/immediate.rs @@ -3,8 +3,8 @@ use crate::sys; use std::ffi::c_void; use std::os::raw::c_char; -/// An immediate expression. Used to set immediate data. -/// Verdicts are handled separately by [crate::expr::Verdict]. +/// An immediate expression. Used to set immediate data. Verdicts are handled separately by +/// [crate::expr::Verdict]. #[derive(Debug, Clone, Eq, PartialEq, Hash)] pub struct Immediate<T> { pub data: T, @@ -50,11 +50,10 @@ impl<const N: usize> Expression for Immediate<[u8; N]> { Immediate::<u8>::get_raw_name() } - /// The raw data contained inside `Immediate` expressions can only be deserialized to - /// arrays of bytes, to ensure that the memory layout of retrieved data cannot be - /// violated. It is your responsibility to provide the correct length of the byte - /// data. If the data size is invalid, you will get the error - /// `DeserializationError::InvalidDataSize`. + /// The raw data contained inside `Immediate` expressions can only be deserialized to arrays of + /// bytes, to ensure that the memory layout of retrieved data cannot be violated. It is your + /// responsibility to provide the correct length of the byte data. If the data size is invalid, + /// you will get the error `DeserializationError::InvalidDataSize`. /// /// Example (warning, no error checking!): /// ```rust @@ -72,12 +71,11 @@ impl<const N: usize> Expression for Immediate<[u8; N]> { /// println!("{:?}", expr.decode_expr::<Immediate<[u8; 1]>>().unwrap()); /// } /// ``` - /// These limitations occur because casting bytes to any type of the same size - /// as the raw input would be *extremely* dangerous in terms of memory safety. - // As casting bytes to any type of the same size as the input would - // be *extremely* dangerous in terms of memory safety, - // rustables only accept to deserialize expressions with variable-size data - // to arrays of bytes, so that the memory layout cannot be invalid. + /// These limitations occur because casting bytes to any type of the same size as the raw input + /// would be *extremely* dangerous in terms of memory safety. + // As casting bytes to any type of the same size as the input would be *extremely* dangerous in + // terms of memory safety, rustables only accept to deserialize expressions with variable-size + // data to arrays of bytes, so that the memory layout cannot be invalid. fn from_expr(expr: *const sys::nftnl_expr) -> Result<Self, DeserializationError> { unsafe { let ref_len = std::mem::size_of::<[u8; N]>() as u32; diff --git a/src/expr/log.rs b/src/expr/log.rs index 5c06897..8d20b48 100644 --- a/src/expr/log.rs +++ b/src/expr/log.rs @@ -73,8 +73,8 @@ pub struct LogGroup(pub u16); pub struct LogPrefix(CString); impl LogPrefix { - /// Create a new LogPrefix from a String. Converts it to CString as needed by nftnl. Note - /// that LogPrefix should not be more than 127 characters long. + /// Creates a new LogPrefix from a String. Converts it to CString as needed by nftnl. Note that + /// LogPrefix should not be more than 127 characters long. pub fn new(prefix: &str) -> Result<Self, LogPrefixError> { if prefix.chars().count() > 127 { return Err(LogPrefixError::TooLongPrefix); diff --git a/src/expr/lookup.rs b/src/expr/lookup.rs index fa12197..a0cc021 100644 --- a/src/expr/lookup.rs +++ b/src/expr/lookup.rs @@ -11,8 +11,7 @@ pub struct Lookup { } impl Lookup { - /// Creates a new lookup entry. - /// May return None if the set have no name. + /// Creates a new lookup entry. May return None if the set has no name. pub fn new<K>(set: &Set<K>) -> Option<Self> { set.get_name().map(|set_name| Lookup { set_name: set_name.to_owned(), diff --git a/src/expr/meta.rs b/src/expr/meta.rs index bf77774..a015f65 100644 --- a/src/expr/meta.rs +++ b/src/expr/meta.rs @@ -14,7 +14,7 @@ pub enum Meta { Iif, /// Packet output interface index (dev->ifindex). Oif, - /// Packet input interface name (dev->name) + /// Packet input interface name (dev->name). IifName, /// Packet output interface name (dev->name). OifName, @@ -32,7 +32,7 @@ pub enum Meta { L4Proto, /// Socket control group (skb->sk->sk_classid). Cgroup, - /// A 32bit pseudo-random number + /// A 32bit pseudo-random number. PRandom, } diff --git a/src/expr/mod.rs b/src/expr/mod.rs index fbf49d6..dc59507 100644 --- a/src/expr/mod.rs +++ b/src/expr/mod.rs @@ -60,29 +60,29 @@ pub use self::wrapper::ExpressionWrapper; #[derive(Debug, Error)] pub enum DeserializationError { #[error("The expected expression type doesn't match the name of the raw expression")] - /// The expected expression type doesn't match the name of the raw expression + /// The expected expression type doesn't match the name of the raw expression. InvalidExpressionKind, #[error("Deserializing the requested type isn't implemented yet")] - /// Deserializing the requested type isn't implemented yet + /// Deserializing the requested type isn't implemented yet. NotImplemented, #[error("The expression value cannot be deserialized to the requested type")] - /// The expression value cannot be deserialized to the requested type + /// The expression value cannot be deserialized to the requested type. InvalidValue, #[error("A pointer was null while a non-null pointer was expected")] - /// A pointer was null while a non-null pointer was expected + /// A pointer was null while a non-null pointer was expected. NullPointer, #[error( "The size of a raw value was incoherent with the expected type of the deserialized value" )] - /// The size of a raw value was incoherent with the expected type of the deserialized value + /// The size of a raw value was incoherent with the expected type of the deserialized value/ InvalidDataSize, #[error(transparent)] - /// Couldn't find a matching protocol + /// Couldn't find a matching protocol. InvalidProtolFamily(#[from] super::InvalidProtocolFamily), } @@ -91,8 +91,8 @@ pub trait Expression { /// Returns the raw name used by nftables to identify the rule. fn get_raw_name() -> *const libc::c_char; - /// Try to parse the expression from a raw nftables expression, - /// returning a [DeserializationError] if the attempted parsing failed. + /// Try to parse the expression from a raw nftables expression, returning a + /// [DeserializationError] if the attempted parsing failed. fn from_expr(_expr: *const sys::nftnl_expr) -> Result<Self, DeserializationError> where Self: Sized, @@ -100,8 +100,8 @@ pub trait Expression { Err(DeserializationError::NotImplemented) } - /// Allocates and returns the low level `nftnl_expr` representation of this expression. - /// The caller to this method is responsible for freeing the expression. + /// Allocates and returns the low level `nftnl_expr` representation of this expression. The + /// caller to this method is responsible for freeing the expression. fn to_expr(&self, rule: &Rule) -> *mut sys::nftnl_expr; } diff --git a/src/expr/nat.rs b/src/expr/nat.rs index 8beaa30..ce6b881 100644 --- a/src/expr/nat.rs +++ b/src/expr/nat.rs @@ -6,9 +6,9 @@ use std::{convert::TryFrom, os::raw::c_char}; #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)] #[repr(i32)] pub enum NatType { - /// Source NAT. Changes the source address of a packet + /// Source NAT. Changes the source address of a packet. SNat = libc::NFT_NAT_SNAT, - /// Destination NAT. Changeth the destination address of a packet + /// Destination NAT. Changes the destination address of a packet. DNat = libc::NFT_NAT_DNAT, } @@ -22,8 +22,8 @@ impl NatType { } } -/// A source or destination NAT statement. Modifies the source or destination address -/// (and possibly port) of packets. +/// A source or destination NAT statement. Modifies the source or destination address (and possibly +/// port) of packets. #[derive(Debug, PartialEq)] pub struct Nat { pub nat_type: NatType, diff --git a/src/expr/payload.rs b/src/expr/payload.rs index 4ba47df..a108fe8 100644 --- a/src/expr/payload.rs +++ b/src/expr/payload.rs @@ -51,7 +51,7 @@ pub struct RawPayloadData { } /// Because deserializing a `Payload` expression is not possible (there is not enough information -/// in the expression itself, this enum should be used to deserialize payloads. +/// in the expression itself), this enum should be used to deserialize payloads. #[derive(Debug, Copy, Clone, Eq, PartialEq)] pub enum RawPayload { LinkLayer(RawPayloadData), diff --git a/src/expr/register.rs b/src/expr/register.rs index f0aed94..a05af7e 100644 --- a/src/expr/register.rs +++ b/src/expr/register.rs @@ -4,8 +4,8 @@ use crate::sys::libc; use super::DeserializationError; -/// A netfilter data register. The expressions store and read data to and from these -/// when evaluating rule statements. +/// A netfilter data register. The expressions store and read data to and from these when +/// evaluating rule statements. #[derive(Debug, Copy, Clone, Eq, PartialEq, Hash)] #[repr(i32)] pub enum Register { diff --git a/src/expr/reject.rs b/src/expr/reject.rs index 2ea0cbf..19752ce 100644 --- a/src/expr/reject.rs +++ b/src/expr/reject.rs @@ -2,13 +2,12 @@ use super::{DeserializationError, Expression, Rule}; use crate::ProtoFamily; use crate::sys::{self, libc::{self, c_char}}; -/// A reject expression that defines the type of rejection message sent -/// when discarding a packet. +/// A reject expression that defines the type of rejection message sent when discarding a packet. #[derive(Debug, Clone, Copy, Eq, PartialEq, Hash)] pub enum Reject { - /// Return an ICMP unreachable packet + /// Returns an ICMP unreachable packet. Icmp(IcmpCode), - /// Reject by sending a TCP RST packet + /// Rejects by sending a TCP RST packet. TcpRst, } diff --git a/src/expr/wrapper.rs b/src/expr/wrapper.rs index 1bcc520..00c555c 100644 --- a/src/expr/wrapper.rs +++ b/src/expr/wrapper.rs @@ -47,7 +47,7 @@ impl ExpressionWrapper { } } - /// Attempt to decode the expression as the type T. + /// Attempts to decode the expression as the type T. pub fn decode_expr<T: Expression>(&self) -> Result<T, DeserializationError> { if let Some(kind) = self.get_kind() { let raw_name = unsafe { CStr::from_ptr(T::get_raw_name()) }; @@ -24,11 +24,9 @@ // option. This file may not be copied, modified, or distributed // except according to those terms. -//! Safe abstraction for [`libnftnl`]. Provides low-level userspace access to the in-kernel -//! nf_tables subsystem. See [`rustables-sys`] for the low level FFI bindings to the C library. -//! -//! Can be used to create and remove tables, chains, sets and rules from the nftables firewall, -//! the successor to iptables. +//! Safe abstraction for [`libnftnl`]. Provides userspace access to the in-kernel nf_tables +//! subsystem. Can be used to create and remove tables, chains, sets and rules from the nftables +//! firewall, the successor to iptables. //! //! This library currently has quite rough edges and does not make adding and removing netfilter //! entries super easy and elegant. That is partly because the library needs more work, but also @@ -43,33 +41,33 @@ //! a number of places where the underlying library is used in an invalid or not intended way. //! Large portions of [`libnftnl`] are also not covered yet. Contributions are welcome! //! -//! # Selecting version of `libnftnl` +//! # Supported versions of `libnftnl` //! -//! See the documentation for the corresponding sys crate for details: [`rustables-sys`]. -//! This crate has the same features as the sys crate, and selecting version works the same. +//! This crate will automatically link to the currently installed version of libnftnl upon build. +//! It requires libnftnl version 1.0.6 or higher. See how the low level FFI bindings to the C +//! library are generated in [`build.rs`](../../../build.rs). //! //! # Access to raw handles //! -//! Retrieving raw handles is considered unsafe and should only ever be enabled if you absoluetely +//! Retrieving raw handles is considered unsafe and should only ever be enabled if you absolutely //! need it. It is disabled by default and hidden behind the feature gate `unsafe-raw-handles`. -//! The reason for that special treatment is we cannot guarantee the lack of aliasing. For example, -//! a program using a const handle to a object in a thread and writing through a mutable handle -//! in another could reach all kind of undefined (and dangerous!) behaviors. -//! By enabling that feature flag, you acknowledge that guaranteeing the respect of safety -//! invariants is now your responsibility! -//! Despite these shortcomings, that feature is still available because it may allow you to perform -//! manipulations that this library doesn't currently expose. If that is your case, we would -//! be very happy to hear from you and maybe help you get the necessary functionality upstream. +//! The reason for that special treatment is we cannot guarantee the lack of aliasing. For +//! example, a program using a const handle to a object in a thread and writing through a mutable +//! handle in another could reach all kind of undefined (and dangerous!) behaviors. By enabling +//! that feature flag, you acknowledge that guaranteeing the respect of safety invariants is now +//! your responsibility! Despite these shortcomings, that feature is still available because it +//! may allow you to perform manipulations that this library doesn't currently expose. If that is +//! your case, we would be very happy to hear from you and maybe help you get the necessary +//! functionality upstream. //! -//! Our current lack of confidence in our availability to provide a safe abstraction over the -//! use of raw handles in the face of concurrency is the reason we decided to settly on `Rc` -//! pointers instead of `Arc` (besides, this should gives us some nice performance boost, not -//! that it matters much of course) and why we do not declare the types exposes by the library -//! as `Send` nor `Sync`. +//! Our current lack of confidence in our availability to provide a safe abstraction over the use +//! of raw handles in the face of concurrency is the reason we decided to settly on `Rc` pointers +//! instead of `Arc` (besides, this should gives us some nice performance boost, not that it +//! matters much of course) and why we do not declare the types exposed by the library as `Send` +//! nor `Sync`. //! //! [`libnftnl`]: https://netfilter.org/projects/libnftnl/ //! [`nftables`]: https://netfilter.org/projects/nftables/ -//! [`rustables-sys`]: https://crates.io/crates/rustables-sys use thiserror::Error; @@ -182,8 +180,8 @@ impl TryFrom<i32> for ProtoFamily { /// # Unsafe /// /// This trait is unsafe to implement because it must never serialize to anything larger than the -/// largest possible netlink message. Internally the `nft_nlmsg_maxsize()` function is used to make -/// sure the `buf` pointer passed to `write` always has room for the largest possible Netlink +/// largest possible netlink message. Internally the `nft_nlmsg_maxsize()` function is used to +/// make sure the `buf` pointer passed to `write` always has room for the largest possible Netlink /// message. pub unsafe trait NlMsg { /// Serializes the Netlink message to the buffer at `buf`. `buf` must have space for at least @@ -202,11 +200,10 @@ where } } -/// The largest nf_tables netlink message is the set element message, which -/// contains the NFTA_SET_ELEM_LIST_ELEMENTS attribute. This attribute is -/// a nest that describes the set elements. Given that the netlink attribute -/// length (nla_len) is 16 bits, the largest message is a bit larger than -/// 64 KBytes. +/// The largest nf_tables netlink message is the set element message, which contains the +/// NFTA_SET_ELEM_LIST_ELEMENTS attribute. This attribute is a nest that describes the set +/// elements. Given that the netlink attribute length (nla_len) is 16 bits, the largest message is +/// a bit larger than 64 KBytes. pub fn nft_nlmsg_maxsize() -> u32 { u32::from(::std::u16::MAX) + unsafe { libc::sysconf(libc::_SC_PAGESIZE) } as u32 } diff --git a/src/query.rs b/src/query.rs index 02c4082..8d54704 100644 --- a/src/query.rs +++ b/src/query.rs @@ -3,8 +3,8 @@ use sys::libc; /// Returns a buffer containing a netlink message which requests a list of all the netfilter /// matching objects (e.g. tables, chains, rules, ...). -/// Supply the type of objects to retrieve (e.g. libc::NFT_MSG_GETTABLE), and optionally -/// a callback to execute on the header, to set parameters for example. +/// Supply the type of objects to retrieve (e.g. libc::NFT_MSG_GETTABLE), and optionally a callback +/// to execute on the header, to set parameters for example. /// To pass arbitrary data inside that callback, please use a closure. pub fn get_list_of_objects<Error>( seq: u32, @@ -54,11 +54,10 @@ mod inner { NetlinkAllocationFailed, } - /// List objects of a certain type (e.g. libc::NFT_MSG_GETTABLE) with the help of an helper + /// List objects of a certain type (e.g. libc::NFT_MSG_GETTABLE) with the help of a helper /// function called by mnl::cb_run2. - /// The callback expect a tuple of additional data (supplied as an argument to - /// this function) and of the output vector, to which it should append the parsed - /// object it received. + /// The callback expects a tuple of additional data (supplied as an argument to this function) + /// and of the output vector, to which it should append the parsed object it received. pub fn list_objects_with_data<'a, A, T>( data_type: u16, cb: fn(&libc::nlmsghdr, &mut (&'a A, &mut Vec<T>)) -> libc::c_int, diff --git a/src/rule.rs b/src/rule.rs index c8cb90d..8d9dfd5 100644 --- a/src/rule.rs +++ b/src/rule.rs @@ -113,7 +113,7 @@ impl Rule { } } - /// Retrieves an iterator to loop over the expressions of the rule + /// Retrieves an iterator to loop over the expressions of the rule. pub fn get_exprs(self: &Rc<Self>) -> RuleExprsIter { RuleExprsIter::new(self.clone()) } @@ -130,12 +130,12 @@ impl Rule { self.rule } - /// Perform a deep comparizon of rules, by checking they have the same expressions inside. - /// This is not enabled by default in our PartialEq implementation because of the - /// difficulty to compare an expression generated by the library with the expressions returned - /// by the kernel when iterating over the currently in-use rules. The kernel-returned - /// expressions may have additional attributes despite being generated from the same rule. - /// This is particularly true for the 'nat' expression). + /// Performs a deep comparizon of rules, by checking they have the same expressions inside. + /// This is not enabled by default in our PartialEq implementation because of the difficulty to + /// compare an expression generated by the library with the expressions returned by the kernel + /// when iterating over the currently in-use rules. The kernel-returned expressions may have + /// additional attributes despite being generated from the same rule. This is particularly true + /// for the 'nat' expression). pub fn deep_eq(&self, other: &Self) -> bool { if self != other { return false; diff --git a/src/rule_methods.rs b/src/rule_methods.rs index 9a8ef58..d7145d7 100644 --- a/src/rule_methods.rs +++ b/src/rule_methods.rs @@ -32,8 +32,7 @@ pub enum Protocol { } /// A RuleMethods trait over [`crate::Rule`], to make it match some criteria, and give it a -/// verdict. Mostly adapted from [talpid-core's -/// firewall](https://github.com/mullvad/mullvadvpn-app/blob/d92376b4d1df9b547930c68aa9bae9640ff2a022/talpid-core/src/firewall/linux.rs). +/// verdict. Mostly adapted from [talpid-core's firewall]. /// All methods return the rule itself, allowing them to be chained. Usage example : /// ```rust /// use rustables::{Batch, Chain, ChainMethods, Protocol, ProtoFamily, Rule, RuleMethods, Table, MsgType, Hook}; @@ -49,38 +48,40 @@ pub enum Protocol { /// .accept() /// .add_to_batch(&mut batch); /// ``` +/// [talpid-core's firewall]: +/// https://github.com/mullvad/mullvadvpn-app/blob/d92376b4d1df9b547930c68aa9bae9640ff2a022/talpid-core/src/firewall/linux.rs pub trait RuleMethods { - /// Match ICMP packets. + /// Matches ICMP packets. fn icmp(self) -> Self; - /// Match IGMP packets. + /// Matches IGMP packets. fn igmp(self) -> Self; - /// Match packets to destination `port` and `protocol`. + /// Matches packets to destination `port` and `protocol`. fn dport(self, port: &str, protocol: &Protocol) -> Result<Self, Error> where Self: std::marker::Sized; - /// Match packets on `protocol`. + /// Matches packets on `protocol`. fn protocol(self, protocol: Protocol) -> Result<Self, Error> where Self: std::marker::Sized; - /// Match packets in an already established connections. + /// Matches packets in an already established connection. fn established(self) -> Self where Self: std::marker::Sized; - /// Match packets going through `iface_index`. Interface indexes can be queried with + /// Matches packets going through `iface_index`. Interface indexes can be queried with /// `iface_index()`. fn iface_id(self, iface_index: libc::c_uint) -> Result<Self, Error> where Self: std::marker::Sized; - /// Match packets going through `iface_name`, an interface name, as in "wlan0" or "lo". + /// Matches packets going through `iface_name`, an interface name, as in "wlan0" or "lo". fn iface(self, iface_name: &str) -> Result<Self, Error> where Self: std::marker::Sized; - /// Add a log instruction to the rule. `group` is the NFLog group, `prefix` is a prefix + /// Adds a log instruction to the rule. `group` is the NFLog group, `prefix` is a prefix /// appended to each log line. fn log(self, group: Option<LogGroup>, prefix: Option<LogPrefix>) -> Self; - /// Match packets whose source IP address is `saddr`. + /// Matches packets whose source IP address is `saddr`. fn saddr(self, ip: IpAddr) -> Self; - /// Match packets whose source network is `snet`. + /// Matches packets whose source network is `snet`. fn snetwork(self, ip: IpNetwork) -> Self; - /// Add the `Accept` verdict to the rule. The packet will be sent to destination. + /// Adds the `Accept` verdict to the rule. The packet will be sent to destination. fn accept(self) -> Self; - /// Add the `Drop` verdict to the rule. The packet will be dropped. + /// Adds the `Drop` verdict to the rule. The packet will be dropped. fn drop(self) -> Self; - /// Append rule to `batch`. + /// Appends this rule to `batch`. fn add_to_batch(self, batch: &mut Batch) -> Self; } @@ -216,7 +217,7 @@ impl RuleMethods for Rule { } } -/// Look up the interface index for a given interface name. +/// Looks up the interface index for a given interface name. pub fn iface_index(name: &str) -> Result<libc::c_uint, Error> { let c_name = CString::new(name)?; let index = unsafe { libc::if_nametoindex(c_name.as_ptr()) }; diff --git a/src/table.rs b/src/table.rs index 2f21453..e6b9559 100644 --- a/src/table.rs +++ b/src/table.rs @@ -8,8 +8,8 @@ use std::{ os::raw::c_char, }; -/// Abstraction of `nftnl_table`. The top level container in netfilter. A table has a protocol -/// family and contain [`Chain`]s that in turn hold the rules. +/// Abstraction of `nftnl_table`, the top level container in netfilter. A table has a protocol +/// family and contains [`Chain`]s that in turn hold the rules. /// /// [`Chain`]: struct.Chain.html pub struct Table { @@ -78,7 +78,7 @@ impl Table { } } - /// Update the userdata of this chain. + /// Updates the userdata of this chain. pub fn set_userdata(&self, data: &CStr) { unsafe { sys::nftnl_table_set_str(self.table, sys::NFTNL_TABLE_USERDATA as u16, data.as_ptr()); |