1.\" $OpenBSD: etherip.4,v 1.10 2024/08/30 20:08:05 jmc Exp $ 2.\" 3.\" Copyright (c) 2015 YASUOKA Masahiko <yasuoka@openbsd.org> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.\" The following requests are required for all man pages. 18.\" 19.Dd $Mdocdate: August 30 2024 $ 20.Dt ETHERIP 4 21.Os 22.Sh NAME 23.Nm etherip 24.Nd EtherIP tunnel interface 25.Sh SYNOPSIS 26.Cd "pseudo-device etherip" 27.Sh DESCRIPTION 28The 29.Nm 30driver provides point-to-point tunnel interfaces for carrying 31Ethernet frames across IPv4 and IPv6 networks using RFC 3378 EtherIP 32encapsulation. 33.Pp 34An 35.Nm 36interface can be created using the 37.Ic ifconfig etherip Ns Ar N Ic create 38command or by setting up a 39.Xr hostname.if 5 40configuration file for 41.Xr netstart 8 . 42It must be configured with the addresses used for the outer header. 43This can be done using 44.Xr ifconfig 8 Ns 's 45.Ic tunnel 46command (which uses the 47.Dv SIOCSLIFPHYADDR 48ioctl). 49The 50.Xr sysctl 2 51variable 52.Dv net.inet.etherip.allow 53must be set to 1, unless 54.Xr ipsec 4 55is being used to protect the traffic. 56.Pp 57.Nm 58interfaces can configured as part of an Ethernet bridge, such as 59.Xr veb 4 , 60.Xr tpmr 4 , 61and 62.Xr bridge 4 , 63to extend the connectivity of Ethernet networks across IP networks, 64possibly across the Internet. 65.Pp 66The EtherIP protocol does not provide any integrated security 67features. 68EtherIP should only be deployed on trusted private networks, or 69protected with IPsec to add authentication and encryption for 70confidentiality. 71IPsec is especially recommended when transporting EtherIP over the 72public Internet. 73EtherIP encapsulated packets may be protected with IPsec by specifying 74the appropriate IPsec flows between the two endpoints. 75To only protect the encapsulated EtherIP traffic between the tunnel 76endpoints, the IP transport protocol 97 (etherip) selector may be used 77in 78.Xr ipsec.conf 5 79or 80.Xr iked.conf 5 . 81.Sh EXAMPLES 82Given two physically separate Ethernet networks, 83.Nm 84can be used as follows to make them appear as the same local area 85network. 86If host gw1 has the external IP address 192.0.2.10 and is connected 87to network1 on em1, and host gw2 has the external IP address 88198.51.100.14 and is connected to network2 on ix1, the following 89configuration can be used to bridge network1 and network2. 90.Pp 91First create a bridge using a 92.Xr veb 4 93interface, 94adding the 95.Nm 96interface and internal Ethernet interface to the bridge. 97.Pp 98On gw1: 99.Bd -literal -offset indent 100gw1# ifconfig etherip0 create tunnel 192.0.2.10 198.51.100.14 101gw1# ifconfig veb0 create add etherip0 add em1 102.Ed 103.Pp 104On gw2: 105.Bd -literal -offset indent 106gw2# ifconfig etherip0 create tunnel 198.51.100.14 192.0.2.10 107gw2# ifconfig veb0 create add etherip0 add ix1 108.Ed 109.Pp 110Create Security Associations (SAs) between the external IP address of each 111bridge and matching ingress flows by using the following 112.Xr ipsec.conf 5 113file on gw1: 114.Bd -literal -offset indent 115esp from 198.51.100.14 to 192.0.2.10 spi 0x4242:0x4243 \e 116 authkey file "auth1:auth2" enckey file "enc1:enc2" 117flow esp proto etherip from 198.51.100.14 to 192.0.2.10 118.Ed 119.Pp 120Now load these rules into the kernel by issuing the 121.Xr ipsecctl 8 122command: 123.Bd -literal -offset indent 124gw1# ipsecctl -f ipsec.conf 125.Ed 126.Pp 127Appropriate 128.Xr ipsec.conf 5 129for gw2: 130.Bd -literal -offset indent 131esp from 198.51.100.14 to 192.0.2.10 spi 0x4243:0x4242 \e 132 authkey file "auth2:auth1" enckey file "enc2:enc1" 133flow esp proto etherip from 198.51.100.14 to 192.0.2.10 134.Ed 135.Pp 136And load them: 137.Bd -literal -offset indent 138gw2# ipsecctl -f ipsec.conf 139.Ed 140.Pp 141Finally, bring all the interfaces up (if not already up). 142.Pp 143On gw1: 144.Bd -literal -offset indent 145gw1# ifconfig em1 up 146gw1# ifconfig etherip0 up 147gw1# ifconfig veb0 up 148.Ed 149.Pp 150On gw2: 151.Bd -literal -offset indent 152gw1# ifconfig ix1 up 153gw1# ifconfig etherip0 up 154gw1# ifconfig veb0 up 155.Ed 156.Sh SEE ALSO 157.Xr sysctl 2 , 158.Xr bridge 4 , 159.Xr inet 4 , 160.Xr inet6 4 , 161.Xr ipsec 4 , 162.Xr tpmr 4 , 163.Xr veb 4 , 164.Xr hostname.if 5 , 165.Xr iked.conf 5 , 166.Xr ipsec.conf 5 , 167.Xr ifconfig 8 , 168.Xr netstart 8 169.Sh STANDARDS 170.Rs 171.%A R. Housley 172.%A S. Hollenbeck 173.%D September 2002 174.%R RFC 3378 175.%T EtherIP: Tunneling Ethernet Frames in IP Datagrams 176.Re 177.Sh HISTORY 178The 179.Nm 180device first appeared in 181.Ox 5.9 . 182.Sh AUTHORS 183The 184.Nm 185driver was written by 186.An Kazuya Goda Aq Mt goda@openbsd.org . 187