tun2/
configuration.rs

1//            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
2//                    Version 2, December 2004
3//
4// Copyleft (ↄ) meh. <meh@schizofreni.co> | http://meh.schizofreni.co
5//
6// Everyone is permitted to copy and distribute verbatim or modified
7// copies of this license document, and changing it is allowed as long
8// as the name is changed.
9//
10//            DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE
11//   TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
12//
13//  0. You just DO WHAT THE FUCK YOU WANT TO.
14
15use std::net::IpAddr;
16#[cfg(unix)]
17use std::os::unix::io::RawFd;
18
19use crate::address::ToAddress;
20use crate::platform::PlatformConfig;
21
22cfg_if::cfg_if! {
23    if #[cfg(windows)] {
24        #[allow(dead_code)]
25        #[derive(Clone, Debug)]
26        pub(crate) struct WinHandle(std::os::windows::raw::HANDLE);
27        unsafe impl Send for WinHandle {}
28        unsafe impl Sync for WinHandle {}
29    }
30}
31
32/// TUN interface OSI layer of operation.
33#[derive(Clone, Copy, Default, Debug, Eq, PartialEq)]
34pub enum Layer {
35    L2,
36    #[default]
37    L3,
38}
39
40/// Configuration builder for a TUN interface.
41#[derive(Clone, Default, Debug)]
42pub struct Configuration {
43    pub(crate) tun_name: Option<String>,
44    pub(crate) platform_config: PlatformConfig,
45    pub(crate) address: Option<IpAddr>,
46    pub(crate) destination: Option<IpAddr>,
47    pub(crate) broadcast: Option<IpAddr>,
48    pub(crate) netmask: Option<IpAddr>,
49    pub(crate) mtu: Option<u16>,
50    pub(crate) enabled: Option<bool>,
51    pub(crate) layer: Option<Layer>,
52    pub(crate) queues: Option<usize>,
53    #[cfg(unix)]
54    pub(crate) raw_fd: Option<RawFd>,
55    #[cfg(not(unix))]
56    pub(crate) raw_fd: Option<i32>,
57    #[cfg(windows)]
58    pub(crate) raw_handle: Option<WinHandle>,
59    #[cfg(windows)]
60    pub(crate) ring_capacity: Option<u32>,
61    #[cfg(windows)]
62    pub(crate) metric: Option<u16>,
63    #[cfg(unix)]
64    pub(crate) close_fd_on_drop: Option<bool>,
65}
66
67impl Configuration {
68    /// Access the platform-dependent configuration.
69    pub fn platform_config<F>(&mut self, f: F) -> &mut Self
70    where
71        F: FnOnce(&mut PlatformConfig),
72    {
73        f(&mut self.platform_config);
74        self
75    }
76
77    /// Functionally equivalent to `tun_name`
78    #[deprecated(
79        since = "1.1.2",
80        note = "Since the API `name` may have an easy name conflict when IDE prompts, it is replaced by `tun_name` for better coding experience"
81    )]
82    pub fn name<S: AsRef<str>>(&mut self, tun_name: S) -> &mut Self {
83        self.tun_name = Some(tun_name.as_ref().into());
84        self
85    }
86
87    /// Set the tun name.
88    ///
89    /// [Note: on macOS, the tun name must be the form `utunx` where `x` is a number, such as `utun3`. -- end note]
90    pub fn tun_name<S: AsRef<str>>(&mut self, tun_name: S) -> &mut Self {
91        self.tun_name = Some(tun_name.as_ref().into());
92        self
93    }
94
95    /// Set the address.
96    pub fn address<A: ToAddress>(&mut self, value: A) -> &mut Self {
97        self.address = Some(value.to_address().unwrap());
98        self
99    }
100
101    /// Set the destination address.
102    pub fn destination<A: ToAddress>(&mut self, value: A) -> &mut Self {
103        self.destination = Some(value.to_address().unwrap());
104        self
105    }
106
107    /// Set the broadcast address.
108    pub fn broadcast<A: ToAddress>(&mut self, value: A) -> &mut Self {
109        self.broadcast = Some(value.to_address().unwrap());
110        self
111    }
112
113    /// Set the netmask.
114    pub fn netmask<A: ToAddress>(&mut self, value: A) -> &mut Self {
115        self.netmask = Some(value.to_address().unwrap());
116        self
117    }
118
119    /// Set the MTU.
120    pub fn mtu(&mut self, value: u16) -> &mut Self {
121        self.mtu = Some(value);
122        self
123    }
124
125    /// Set the interface to be enabled once created.
126    pub fn up(&mut self) -> &mut Self {
127        self.enabled = Some(true);
128        self
129    }
130
131    /// Set the interface to be disabled once created.
132    pub fn down(&mut self) -> &mut Self {
133        self.enabled = Some(false);
134        self
135    }
136
137    /// Set the OSI layer of operation.
138    pub fn layer(&mut self, value: Layer) -> &mut Self {
139        self.layer = Some(value);
140        self
141    }
142
143    /// Set the number of queues.
144    /// Note: The queues must be 1, otherwise will failed.
145    #[deprecated(since = "1.0.0", note = "The queues will always be 1.")]
146    pub fn queues(&mut self, value: usize) -> &mut Self {
147        self.queues = Some(value);
148        self
149    }
150
151    /// Set the raw fd.
152    #[cfg(unix)]
153    pub fn raw_fd(&mut self, fd: RawFd) -> &mut Self {
154        self.raw_fd = Some(fd);
155        self
156    }
157    #[cfg(not(unix))]
158    pub fn raw_fd(&mut self, fd: i32) -> &mut Self {
159        self.raw_fd = Some(fd);
160        self
161    }
162    #[cfg(windows)]
163    pub fn raw_handle(&mut self, handle: std::os::windows::raw::HANDLE) -> &mut Self {
164        self.raw_handle = Some(WinHandle(handle));
165        self
166    }
167    #[cfg(windows)]
168    pub fn ring_capacity(&mut self, ring_capacity: u32) -> &mut Self {
169        self.ring_capacity = Some(ring_capacity);
170        self
171    }
172    #[cfg(windows)]
173    pub fn metric(&mut self, metric: u16) -> &mut Self {
174        self.metric = Some(metric);
175        self
176    }
177    /// Set whether to close the received raw file descriptor on drop or not.
178    /// The default behaviour is to close the received or tun2 generated file descriptor.
179    /// Note: If this is set to false, it is up to the caller to ensure the
180    /// file descriptor that they pass via [Configuration::raw_fd] is properly closed.
181    #[cfg(unix)]
182    pub fn close_fd_on_drop(&mut self, value: bool) -> &mut Self {
183        self.close_fd_on_drop = Some(value);
184        self
185    }
186}
tun2/configuration.rs

tun2/
configuration.rs
