diff --git a/tncattach.8 b/tncattach.8 new file mode 100644 index 0000000..f41390f --- /dev/null +++ b/tncattach.8 @@ -0,0 +1,165 @@ +.TH tncattach 8 "September 12, 2020" + +.SH NAME +. +. +tncattach \- Attach TNC devices as system network interfaces + +.SH SYNOPSIS +. +. +\f[B]tncattach\f[R] [OPTION...] port baudrate + +.SH DESCRIPTION +Attach KISS TNC devices as network interfaces in Linux. This program allows you to attach TNCs or any KISS-compatible device as a network interface. This program does not need any kernel modules, and has no external dependencies outside the standard Linux and GNU C libraries. + +.SH OPTIONS +. +. +.TP +.BI \-m, \-\-mtu=MTU +. +Specify interface MTU +. +. +.TP +.BI \-e, \-\-ethernet +Create a full ethernet device +. +. +.TP +.BI \-i, \-\-ipv4=IP_ADDRESS +Configure an IPv4 address on interface +. +. +.TP +.BI \-n, \-\-noipv6 +Filter IPv6 traffic from reaching TNC +. +. +.TP +.BI \-\-noup +Only create interface, don't bring it up +. +. +.TP +.BI \-T, \-\-kisstcp +Use KISS over TCP instead of serial port +. +. +.TP +.BI \-H, \-\-tcphost=TCP_HOST +Host to connect to when using KISS over TCP +. +. +.TP +.BI \-P, \-\-tcpport=TCP_PORT +TCP port when using KISS over TCP +. +. +.TP +.BI \-t, \-\-interval=SECONDS +Maximum interval between station identifications +. +. +.TP +.B \-s, \-\-id=CALLSIGN +Station identification data +. +. +.TP +.BI \-d, \-\-daemon +Run tncattach as a daemon +. +. +.TP +.BI \-v, \-\-verbose +Enable verbose output +. +. +.TP +.BI \-?, \-\-help +Show help +. +. +.TP +.BI \-\-usage +Give a short usage message +. +. +.TP +.BI \-V, \-\-version +Print program version +. +. + +.SH USAGE +The program supports attaching TNCs as point-to-point tunnel devices, or generic ethernet devices. The ethernet mode is suitable for point-to-multipoint setups, and can be enabled with the corresponding command line switch. If you only need point-to-point links, it is advisable to just use the standard point-to-point mode, since it doesn't incur the ethernet header overhead on each packet. +.P +If you want to connect to a virtual KISS TNC over a TCP connection, you can use the -T option, along with the -H and -P options to specify the host and port. +.P +Additionally, it is worth noting that tncattach can filter out IPv6 packets from reaching the TNC. Most operating systems attempts to autoconfigure IPv6 when an interface is brought up, which results in a substantial amount of IPv6 traffic generated by router solicitations and similar, which is usually unwanted for packet radio links and similar. +.P +If you intend to use tncattach on a system with mDNS services enabled (avahi-daemon, for example), you may want to consider modifying your mDNS setup to exclude TNC interfaces, or turning it off entirely, since it will generate a lot of traffic that might be unwanted. + +.SH STATION IDENTIFICATION + +You can configure tncattach to automatically transmit station identification beacons according to a given interval, by using the --id and --interval options. Identification will be transmitted as raw data frames with whatever content has been specified in the --id option. Useful for amateur radio use, or other areas where station identification is necessary. +.P +Identification beacons will be transmitted when: +.P +.IP +There is outgoing data to send, and the specified interval has elapsed. +.IP +The specified interval elapses, and data has been sent since the last ID beacon. +.IP +The program exits, if any data frames have been transmitted since the last ID beacon. +.P +The above methodology should comply with station identification rules for amateur radio in most parts of the world, and complies with US Part 97 rules. + +.SH EXAMPLES +. +Create an ethernet device with a USB-connected TNC, set the MTU, filter IPv6 traffic, and set an IPv4 address: +.IP +sudo tncattach /dev/ttyUSB0 115200 --ethernet --mtu 576 --noipv6 --ipv4 10.92.0.10/24 +.P +Create an ethernet device with a TCP-connected TNC, set the MTU, filter IPv6 traffic, and set an IPv4 address: +.IP +sudo tncattach -T -H localhost -P 8001 --ethernet --mtu 576 --noipv6 --ipv4 10.92.0.10/24 +.P +You can interact with the interface like any other using the ip or ifconfig utilities. +.p +Check interface is running: +.P +# ifconfig +.br +tnc0: flags=4305<UP,POINTOPOINT,RUNNING,NOARP,MULTICAST> mtu 400 +.br + inet 10.93.0.1 netmask 255.255.255.255 destination 10.93.0.2 +.br + unspec 00-00-00-00-00-00-00-00-00-00-00-00-00-00-00-00 txqueuelen 500 (UNSPEC) +.br + RX packets 0 bytes 0 (0.0 B) +.br + RX errors 0 dropped 0 overruns 0 frame 0 +.br + TX packets 0 bytes 0 (0.0 B) +.br + TX errors 0 dropped 0 overruns 0 carrier 0 collisions 0 +.P +.SH WORTH KNOWING ON RASPBIAN +On some versions of Raspbian (and probably other operating systems), the DHCP client daemon dhcpcd interferes with TNC interfaces, by overriding their MTU and trying to auto-configure link-local addresses. You probably don't want this, and it can be disabled by editing the /etc/dhcpcd.conf file, adding a statement telling dhcpcd to ignore your TNC interface: +.P +# Add the following statement somewhere at the beginning +.br +# of /etc/dhcpcd.conf to prevent dhcpcd from changing MTU +.br +denyinterfaces tnc0 + +.SH SEE ALSO + +rnodeconfigutil(8) + +.SH AUTHOR + +Mark Qvist