documenting arper

diff --git a/arper.lsp.8.adoc b/arper.lsp.8.adoc
new file mode 100644 (file)
index 0000000..0c7d53f
--- /dev/null
+++ b/arper.lsp.8.adoc
@@ -0,0 +1,94 @@
+= arper.lsp(8)
+:doctype: manpage
+:revdate: {sys:date "+%Y-%m-%d %H:%M:%S"}
+:COLON: :
+:EQUALS: =
+
+== NAME
+
+arper.lsp - Emulate ipv4 presence on a tap by responding to ARP and ICMP.
+
+== SYNOPSIS
+
+*./arper.lsp* *-t* _tap_ _conf__
+
+== DESCRIPTION
+
+The *arper.lsp* program implements ARP and ICMP responding on a given
+_tap_ interface for a selection of ipv4 addresses as specified in the
+given configuration file. This emulates the presence of one or more
+ipv4 hosts, as if the _tap_ was interfacing a network.
+
+The configuration file has lines of "ipv4 mac comment" to declare
+pairs of IP and MAC addresses to emulate.
+
+Note that the _tap_ must be configured separately.
+
+== EXAMPLE
+
+=== Emulating a single host
+
+The configuration, "single", is as follows:
+----
+    192.168.1.2 02:00:00:00:00:02 some "random" host
+----
+
+Commandline:
+----
+# ./arper.lsp -t tap0 single &
+# ifconfig tap0 192.168.1.1/24 up
+# ping -n 192.168.1.2
+# fg^C
+----
+
+=== Emulating three host on local network
+
+The configuration, "triple", is as follows:
+----
+    192.168.1.2 02:00:00:00:00:02 some "random" host
+    192.168.1.20 02:00:00:00:00:02 another "random" host
+    192.168.1.200 02:00:00:00:00:02 and another "random" host
+----
+
+Commandline:
+----
+# ./arper.lsp -t tap0 single &
+# ifconfig tap0 192.168.1.1/24 up
+# ping -c 3 -n 192.168.1.2
+# ping -c 3 -n 192.168.1.20
+# ping -c 3 -n 192.168.1.22
+# ping -c 3 -n 192.168.1.200
+# fg^C
+----
+
+Note that +192.168.1.22+ is not emulated.
+
+=== Emulating hosts on several network
+
+The configuration, "triss", is as follows:
+----
+    192.168.1.2 02:00:00:00:00:02 some "random" host
+    192.168.2.2 02:00:00:00:00:02 another "random" host
+    192.168.3.2 02:00:00:00:00:02 and another "random" host
+----
+
+Commandline:
+----
+# ./arper.lsp -t tap0 single &
+# ifconfig tap0 192.168.1.1/24 up
+# ip addr add 192.168.2.1/24 dev tap0
+# ip addr add 192.168.3.1/24 dev tap0
+# ping -c 3 -n 192.168.1.2
+# ping -c 3 -n 192.168.2.2
+# ping -c 3 -n 192.168.3.2
+# fg^C
+----
+
+=== NOTES
+
+The *arper.lsp* script is prepared for handling ipv6 packets, but it
+does not include any Neighbor Discovery activity.
+
+== AUTHOR
+
+Copyright 2021 Ralph Ronnquist <ralph.ronnquist@gmail.com>