Merge pull request #36 from fragglet/modularize-branch

Merge modularize-branch

Author: fragglet

.github/workflows/go.yml

@@ -52,6 +52,9 @@ jobs:
         cd artifacts
         go build -tags nopcap -v ../ipxbox.go
         go build -tags nopcap -v ../standalone/ipxbox_uplink.go
+        go build -tags nopcap -v ../standalone/standalone_ipxpkt.go
+        go build -tags nopcap -v ../standalone/standalone_pptp.go
+        go build -tags nopcap -v ../standalone/standalone_qproxy.go
       env:
         GOARCH: ${{ matrix.goarch }}
         GOOS: ${{ matrix.goos }}

.gitignore

@@ -0,0 +1,6 @@
+*.exe
+ipxbox
+ipxbox_uplink
+standalone_ipxpkt
+standalone_pptp
+standalone_qproxy

.lvimrc

@@ -1,5 +1,5 @@
 " Local vimrc configuration file.  Install the localvimrc.vim vim script.
-setlocal tabstop=8 softtabstop=8 shiftwidth=8 noexpandtab cindent
+setlocal tabstop=8 softtabstop=8 shiftwidth=8 noexpandtab smartindent nocindent
 if &ft == "markdown"
 	setlocal softtabstop=4 shiftwidth=4 expandtab smartindent nocindent
 endif

BRIDGE-HOWTO.md

@@ -14,9 +14,13 @@ a lot of damage you can do with the IPX protocol nowadays but there's still the
 possibility that if you use this on a public server, you might be exposing
 something on your network that you don't intend to.
 
-There are two ways to set things up: `ipxbox` can either create a TAP device
-(use `--enable_tap`) or use `libpcap` to connect to a real Ethernet device.
-If you don't know what this means, you'll want to use the `libpcap` approach.
+There are two ways to set things up: `ipxbox` can either create a
+[TAP device](https://en.wikipedia.org/wiki/TUN/TAP) or use
+[`libpcap`](https://en.wikipedia.org/wiki/Pcap)
+to connect to a real Ethernet device. If you don't know what this means,
+you'll want to use the `libpcap` approach.
+
+## Bridging with libpcap
 
 Find out which Ethernet interface (network card) you want to use by using the
 Linux `ifconfig` command. Usually the interface will be named something like
@@ -29,9 +33,9 @@ sudo setcap cap_net_raw,cap_net_admin=eip ./ipxbox
 ```
 On other systems (BSD, etc.) only the `root` user can access raw sockets.
 
-Next run `ipxbox` with the `--pcap_device` argument, eg.
+Next run `ipxbox` with the `--bridge` argument, eg.
 ```
-./ipxbox --port=10000 --pcap_device=eth0
+./ipxbox --port=10000 --bridge=pcap:eth0
 ```
 If working correctly, clients connecting to the server will now be bridged to
 `eth0`. You can test this using `tcpdump` to listen for IPX packets and
@@ -47,6 +51,39 @@ listening on eth0, link-type EN10MB (Ethernet), capture size 262144 bytes
 05:08:48.888311 IPX 00000000.02:cf:0d:86:54:e5.0002 > 00000000.02:ff:ff:ff:00:00.0002: ipx-#2 0
 ```
 
+## Using a TAP device
+
+To use TAP instead of pcap, specify `--bridge=tap` instead. For example:
+```
+./ipxbox --bridge=tap
+```
+creates a new network device while the server is running:
+```
+$ ifconfig -a
+tap0: flags=4098<BROADCAST,MULTICAST>  mtu 1500
+        ether 9e:db:a8:4b:d2:19  txqueuelen 1000  (Ethernet)
+        RX packets 0  bytes 0 (0.0 B)
+        RX errors 0  dropped 0  overruns 0  frame 0
+        TX packets 0  bytes 0 (0.0 B)
+        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
+```
+Note that the TAP device will be down by default and you will need to bring
+it up yourself with `ifconfig tap0 up`.
+
+You can also specify the name; for example:
+```
+./ipxbox --bridge=tap:blerg
+```
+produces:
+```
+$ ifconfig -a
+blerg: flags=4098<BROADCAST,MULTICAST>  mtu 1500
+        ether 16:91:8d:c6:d1:4c  txqueuelen 1000  (Ethernet)
+        RX packets 0  bytes 0 (0.0 B)
+        RX errors 0  dropped 0  overruns 0  frame 0
+        TX packets 0  bytes 0 (0.0 B)
+        TX errors 0  dropped 0 overruns 0  carrier 0  collisions 0
+```
 ## Configuring frame type
 
 After following the above instructions you might find problems getting a
@@ -69,7 +106,7 @@ the first thing to check.
 format can be changed by using the `--ethernet_framing` command line flag.
 For example:
 ```
-./ipxbox --port=10000 --pcap_device=eth0 --ethernet_framing=eth-ii
+./ipxbox --port=10000 --bridge=pcap:eth0 --ethernet_framing=eth-ii
 ```
 
 | `--ethernet_framing` value | Description | Notes |
@@ -151,37 +188,45 @@ problems you can disable autodetection and manually specify it.
 | `snap` | Ethernet 802.2 SNAP | 802.3 with 802.2 LLC and SNAP headers |
 | `eth-ii` | Ethernet II | Ethernet II |
 
-## Advanced topic: TCP/IP over IPX
+## Advanced topic: TCP/IP over IPX (ipxpkt)
 
 Much DOS software that communicates over the network (particularly using the
 TCP/IP protocol stack used on the Internet) uses the
 [packet driver](https://en.wikipedia.org/wiki/PC/TCP_Packet_Driver) interface.
 There are packet drivers available for most network cards, providing a
 standard interface for sending and receiving data over the network.
-
 Some forks of DOSbox can emulate the Novell NE2000 card, allowing such
 software to be used. However, vanilla DOSbox at the time of writing does not
 include this feature. Furthermore, it typically requires granting DOSbox
 special permission to be able to send and receive raw network packets.
-The [`ipxpkt.com`](ipxpkt/driver/) driver is a packet driver that tunnels an
-Ethernet link over IPX packets, and ipxbox includes support for its protocol.
-This allows DOSbox users to use packet driver-based software.
+
+The [`ipxpkt.com`](module/ipxpkt/driver/) driver is a packet driver that
+tunnels an Ethernet link over IPX packets, and ipxbox includes support for its
+protocol. This allows you to use packet driver-based software from within
+vanilla DOSbox; you can [see a demo video
+here](https://www.youtube.com/watch?v=5VeVaFbORhI).
 
 **First, a word of warning**: the DOSBox IPX protocol is completely insecure.
 There's no encryption or authentication supported, and enabling this feature
-gives a potential backdoor into the network where the ipxbox server is running.
-If you don't understand the implications of this, don't enable this feature
-on a public-facing ipxbox server.
+gives a backdoor into the network where the ipxbox server is running. If you
+don't understand the implications of this, don't enable this feature on a
+public-facing ipxbox server.
 
 To use this feature:
 
-1. First set up an IPX bridge by following the instructions from the previous
-section.
+1. Install the [`libslirp-helper`](https://packages.debian.org/sid/libslirp-helper)
+package (on Debian; it is available on other Linux distros too).
+
+    - libslirp provides a connection to a simulated network without
+      requiring any special permissions. Alternatively, you can bridge the
+      ipxpkt packets to a real, physical network. Follow the instructions
+      from the previous section about setting up an IPX bridge, but use the
+      `--ipxpkt_bridge` flag instead of `--bridge`.
 
 2. Read the warning in the paragraph above this list. Then add
 `--enable_ipxpkt` to the ipxbox command line. For example:
 ```
-./ipxbox --port=10000 --pcap_device=eth0 --enable_ipxpkt
+./ipxbox --port=10000 --enable_ipxpkt
 ```
 3. Start a DOSbox client and connect to the server as normal. Make sure to
 mount a directory containing the [`ipxpkt.com`](ipxpkt/driver/) driver.
@@ -204,8 +249,9 @@ My Ethernet address is 02:57:04:31:68:FA
 C:\>
 ```
 5. Test the connection is working correctly by trying some software that uses
-the packet driver interface. The [mTCP stack](http://www.brutman.com/mTCP/)
-makes for a good first step. For example:
+the packet driver interface (but don't use `ping` because it won't work in
+Slirp). The [mTCP stack](http://www.brutman.com/mTCP/) makes for a good first
+step. For example:
 ```
 C:\>set mtcpcfg=c:\mtcp\mtcp.cfg
 C:\>dhcp
@@ -220,26 +266,40 @@ DHCP request sent, attempt 1: Offer received, Acknowledged
 
 Good news everyone!
 
-IPADDR 192.168.128.45
-NETMASK 255.255.0.0
-GATEWAY 192.168.60.1
-NAMESERVER 8.8.8.8
+IPADDR 10.0.2.15
+NETMASK 255.255.255.0
+GATEWAY 10.0.2.2
+NAMESERVER 10.0.2.3
 LEASE_TIME 86400 seconds
 
 Settings written to 'c:\mtcp\mtcp.cfg'
 
-C:\>ping 8.8.8.8
+C:\>ftp ftp.freebsd.org
 
-mTCP Ping by M Brutman ([email protected]) (C)opyright 2009-2020
-Version: Mar  7 2020
+mTCP FTP by M Brutman ([email protected]) (C)opyright 2008-2025
+Version: Jan 10 2025
+
+FTP server resolved in 0.00 seconds
+
+Opening control connection to 96.47.72.116:21 with local port 1914
+Connected
 
-ICMP Packet payload is 32 bytes.
+220 This is ftp0.nyi.freebsd.org - hosted at NYI.net.
+Userid: anonymous
+331 Please specify the password.
+Password:
+230-
+230-This is ftp0.nyi.FreeBSD.org, graciously hosted by
+230-365 Data Centers - 365DataCenters.com
+230-
+230-FreeBSD files can be found in the /pub/FreeBSD directory.
+230-
+230 Login successful.
 
-Packet sequence number 0 received in 45.90 ms, ttl=114
-Packet sequence number 1 received in 44.20 ms, ttl=114
-Packet sequence number 2 received in 41.65 ms, ttl=114
-Packet sequence number 3 received in 54.40 ms, ttl=114
+Setting the server file transfer mode to BIN
+200 Switching to Binary mode.
+File transfer mode set to BIN.
 
-Packets sent: 4, Replies received: 4, Replies lost: 0
-Average time for a reply: 46.53 ms (not counting lost packets)
+--> quit
+221 Goodbye.
 ```

PPTP-HOWTO.md

@@ -5,6 +5,8 @@ Me. If you have a retro computer running one of these operating systems,
 you can therefore use this feature to connect to a server and play with
 DOSbox clients (or others using PPTP as well).
 
+You can [see a demo video here](https://www.youtube.com/watch?v=ut37z6EE5Hc).
+
 ## Client setup
 
 First check that the `ipxbox` server you're connecting to has PPTP

client/dosbox/client.go

@@ -19,7 +19,8 @@ import (
 const maxConnectAttempts = 5
 
 var (
-	_ = (network.Node)(&client{})
+	_ = (network.Node)(&connection{})
+	_ = (network.Network)(&Client{})
 )
 
 type connectFailure struct {
@@ -34,26 +35,26 @@ func (cf *connectFailure) Unwrap() error {
 	return os.ErrDeadlineExceeded
 }
 
-type client struct {
+type connection struct {
 	inner  ipx.ReadWriteCloser
 	rxpipe ipx.ReadWriteCloser
 	addr   ipx.Addr
 }
 
-func (c *client) ReadPacket(ctx context.Context) (*ipx.Packet, error) {
+func (c *connection) ReadPacket(ctx context.Context) (*ipx.Packet, error) {
 	return c.rxpipe.ReadPacket(ctx)
 }
 
-func (c *client) WritePacket(packet *ipx.Packet) error {
+func (c *connection) WritePacket(packet *ipx.Packet) error {
 	return c.inner.WritePacket(packet)
 }
 
-func (c *client) Close() error {
+func (c *connection) Close() error {
 	c.rxpipe.Close()
 	return c.inner.Close()
 }
 
-func (c *client) GetProperty(x interface{}) bool {
+func (c *connection) GetProperty(x interface{}) bool {
 	switch x.(type) {
 	case *ipx.Addr:
 		*x.(*ipx.Addr) = c.addr
@@ -63,7 +64,7 @@ func (c *client) GetProperty(x interface{}) bool {
 	}
 }
 
-func (c *client) sendPingReply(addr *ipx.Addr) {
+func (c *connection) sendPingReply(addr *ipx.Addr) {
 	c.inner.WritePacket(&ipx.Packet{
 		Header: ipx.Header{
 			Dest: ipx.HeaderAddr{
@@ -82,7 +83,7 @@ func isPing(hdr *ipx.Header) bool {
 	return hdr.Dest.Addr == ipx.AddrBroadcast && hdr.Dest.Socket == 2
 }
 
-func (c *client) recvLoop(ctx context.Context) {
+func (c *connection) recvLoop(ctx context.Context) {
 	for {
 		packet, err := c.inner.ReadPacket(ctx)
 		if errors.Is(err, io.ErrClosedPipe) {
@@ -156,7 +157,7 @@ func Dial(ctx context.Context, addr string) (network.Node, error) {
 	if err != nil {
 		return nil, err
 	}
-	c := &client{
+	c := &connection{
 		inner:  udp,
 		rxpipe: pipe.New(),
 	}
@@ -167,3 +168,15 @@ func Dial(ctx context.Context, addr string) (network.Node, error) {
 	go c.recvLoop(context.Background())
 	return c, nil
 }
+
+// Client is an implementation of network.Network that creates a new connection
+// to a remote dosbox server for every new node created.
+type Client struct {
+	// TODO: It's bad practice to save a context in a struct:
+	Context context.Context
+	Address string
+}
+
+func (c *Client) NewNode() (network.Node, error) {
+	return Dial(c.Context, c.Address)
+}