From 34ca10e358bbe0470b3b34c9b3918f42d01f92aa Mon Sep 17 00:00:00 2001 From: Jason Lethbridge Date: Fri, 29 Aug 2025 02:27:59 +1000 Subject: [PATCH 1/5] Added MAC address configuration with dhcpcd hook. --- docs/advanced/network.md | 70 ++++++++++++++++++++++++++++++++++++++++ 1 file changed, 70 insertions(+) diff --git a/docs/advanced/network.md b/docs/advanced/network.md index fb16354a..36267cfe 100644 --- a/docs/advanced/network.md +++ b/docs/advanced/network.md @@ -148,6 +148,76 @@ too many to be discussed here. Instead, will cover the most likely reasons you would want to modify the way `dhcpcd` behaves on a MiSTer. For full documentation read [dhcpcd.conf (5)](https://man.archlinux.org/man/dhcpcd.conf.5){target=blank}. +### MAC address configuration +A MAC address (medium access control address) is a network address assigned +to the hardware of every network interface. +It allows network switches to learn where traffic should be routed to. +It can be thought of like an IP address but statically assigned to hardware and only relevant within your local network. + +Much like IP addresses, MAC addresses have to be unique for the network to function properly, +but unlike IP addresses, they cannot be dynamically assigned by a DHCP server, MAC addresses are static by design. +Most vendors work around this problem by shipping their products with a random MAC address from the factory. +The idea being the sheer number of MAC addresses being randomly assigned +means the chance of the same MAC address being used in the same local network and causing a conflict is very low. + +Due to the way the DE-10 nano is built, +it is common that two or more MiSTers will have the exact same MAC address on their onboard ethernet port. +If two such MiSTers are on the same network at the same time, then the +network switches between them might send packets to the wrong MiSTer +and cause connections to fail for what appears to be no reason. +Fortunately, it's possible to override the default MAC address. + +#### Login to Linux terminal on the MiSTer +From the MiSTers startup menu, press ++F9++ to get a Linux terminal then +login as root (see [Network Access](#network-access) for the default credentials). + +#### Check MAC address +Remove the cord from your MiSTers built-in ethernet if there is one attached +then run the command `ip link` by typing it and pressing ++Enter++. +You should get a result somewhat like this: +``` +1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: eth0: mtu 1500 qdisc mq state DOWN mode DEFAULT group default qlen 1000 + link/ether 02:03:04:05:06:07 brd ff:ff:ff:ff:ff:ff permaddr 02:03:04:05:06:07 +``` +`eth0` should be the built-in ethernet on the DE-10 nano while `link/ether` is the currently assigned MAC address +and `permaddr` is the hardware default MAC address if no other is given. + +Repeat these first two steps on all you MiSTers and continue on each one that has the same `link/ether` as another. + +#### Override MAC address +> Let's assume you want the network interface named `eth0` to be assigned a MAC address of `01:02:03:04:05:06`. +Replace these values with the conflicting network interface name you saw in the previous step +and the MAC address you want to set it to. +You can choose any MAC address you like, so long as it is **not** used by **any** other device. +> +> A valid MAC address is six sets of two digits between `01` and `fe` each seperated by a `:` character. + +Run the command `nano /etc/dhcpcd.enter-hook` to edit or create the file then write the following +``` +if [ "$interface" = "eth0" ]; then + ip link set dev "$interface" address 01:02:03:04:05:06 +fi +``` + +Once done, press ++Ctrl+o++ to make `nano` save `dhcpcd.enter-hook` then ++Ctrl+x++ to exit `nano`. +Run the command `reboot` to restart the MiSTer back to the startup menu with the new network settings applied. + +#### Verify the new MAC address applied +Login to root on the Linux terminal the same way you did before and run the command `ip link` again. +You should get a result somewhat like this: +``` +1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 + link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 +2: eth0: mtu 1500 qdisc mq state DOWN mode DEFAULT group default qlen 1000 + link/ether 01:02:03:04:05:06 brd ff:ff:ff:ff:ff:ff permaddr 02:03:04:05:06:07 +``` +`link/ether` should be the same MAC address you set in `/etc/dhcpcd.enter-hook`. +If it is, you can now reattach the cord to this MiSTers built-in ethernet. +In the unlikely event that the new MAC address you chose conflicts with another device on your network +then replace that MAC address in `dhcpcd.enter-hook` with another random MAC address and `reboot` again. + ### Hostname configuration `dhcpcd` can be configured so that MiSTer offers its preferred name to your DHCP server, but it's disabled by default. Enabling it will allow you to connect to your MiSTer by a designated name From 42a542978bd2f11567d7dee1de39f6a9c2498f7c Mon Sep 17 00:00:00 2001 From: Jason Lethbridge Date: Fri, 29 Aug 2025 02:33:01 +1000 Subject: [PATCH 2/5] Be consistent in explaining how to run a command the first time it's mentioned under each main header. --- docs/advanced/network.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) diff --git a/docs/advanced/network.md b/docs/advanced/network.md index 36267cfe..1938d5d3 100644 --- a/docs/advanced/network.md +++ b/docs/advanced/network.md @@ -234,7 +234,7 @@ This is recommended if possible as you will be able to copy and paste the comman Before enabling this feature, you should be sure that your network router supports top-level domains (TLDs) in the local network. -To do this, run the command `dhcpcd -U | less` and press ++Enter++ +To do this, run the command `dhcpcd -U | less` by typing it and pressing ++Enter++ then use the ++Down++ and ++Up++ keys to search for at least one `domain_name` entry that looks somewhat like this: ``` domain_name=lan @@ -255,8 +255,8 @@ lan ``` #### Enable sending preferred name to DHCP server -Open dhcpcd configuration file for editing by running the command `nano /etc/dhcpcd.conf` -(or `vi /etc/dhcpcd.conf` if you know what that is and prefer it) and press ++Enter++. +Open dhcpcd configuration file for editing by running the command `nano /etc/dhcpcd.conf` +by typing it and pressing ++Enter++. Press ++Down++ until you find this text: ``` @@ -354,8 +354,7 @@ The interface names are case-sensitive. Replace these values with the network interface name you got in the previous step and the IP address you want to set it to. -Open dhcpcd configuration file for editing by running the command `nano /etc/dhcpcd.conf` -(or `vi /etc/dhcpcd.conf` if you know what that is and prefer it). +Open dhcpcd configuration file for editing by running the command `nano /etc/dhcpcd.conf`. Press ++Down++ until you're at the bottom of the file then type the following: ``` interface eth0 From 8a9e3116590a473ecaa4b526da0581ba573d2456 Mon Sep 17 00:00:00 2001 From: Jason Lethbridge Date: Fri, 29 Aug 2025 05:51:32 +1000 Subject: [PATCH 3/5] Fixed the complex command that gives you the domain name value. --- docs/advanced/network.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/advanced/network.md b/docs/advanced/network.md index 1938d5d3..92a7f9d2 100644 --- a/docs/advanced/network.md +++ b/docs/advanced/network.md @@ -244,9 +244,9 @@ If you find more than one `domain_name` value, remember them all. If you have no `domain_name` value in the results then your network router is not offering a top level domain and there's no point in proceeding. -Alternatively, you can run this command: +Alternatively, you can run this more complex command: ```bash -dhcpcd -U | 2>/dev/null | grep domain_name= | cut -c13- +dhcpcd -U 2>/dev/null | grep domain_name= | cut -c13- ``` ...which will find and filter `domain_name` values for you. The result of which would look like this instead: From ffd3e4ba427357518a3802a7acf62d6d34422fc6 Mon Sep 17 00:00:00 2001 From: Jason Lethbridge Date: Fri, 29 Aug 2025 14:49:20 +1000 Subject: [PATCH 4/5] Mention Mr Fusion randomizing MAC addresses on setup. --- docs/advanced/network.md | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/docs/advanced/network.md b/docs/advanced/network.md index 92a7f9d2..34a11878 100644 --- a/docs/advanced/network.md +++ b/docs/advanced/network.md @@ -160,12 +160,13 @@ Most vendors work around this problem by shipping their products with a random M The idea being the sheer number of MAC addresses being randomly assigned means the chance of the same MAC address being used in the same local network and causing a conflict is very low. -Due to the way the DE-10 nano is built, -it is common that two or more MiSTers will have the exact same MAC address on their onboard ethernet port. -If two such MiSTers are on the same network at the same time, then the -network switches between them might send packets to the wrong MiSTer -and cause connections to fail for what appears to be no reason. -Fortunately, it's possible to override the default MAC address. +Some operating systems like [Mr Fusion](../setup/software.md#flash-mr-fusion-to-your-microsd) +will randomize the MiSTers MAC address during setup while other installers will use the same MAC address everytime. +Therefore, it is common that two or more MiSTers will have the exact same MAC address on their onboard ethernet port. + +If two MiSTers with the same MAC address are on the same network at the same time, +the network switches may start sending packets to the wrong MiSTer and cause connections to fail. +Fortunately, if this is the case, it's possible to override the default MAC address. #### Login to Linux terminal on the MiSTer From the MiSTers startup menu, press ++F9++ to get a Linux terminal then From 6f0296da0e205fa39559d938a13d3a6addea38ba Mon Sep 17 00:00:00 2001 From: Jason Lethbridge Date: Fri, 29 Aug 2025 17:21:13 +1000 Subject: [PATCH 5/5] Use u-boot.txt method of changing MAC addresses instead of dhcpcd enter hooks. --- docs/advanced/network.md | 65 +++++++++++----------------------------- 1 file changed, 17 insertions(+), 48 deletions(-) diff --git a/docs/advanced/network.md b/docs/advanced/network.md index 34a11878..e07f0fd6 100644 --- a/docs/advanced/network.md +++ b/docs/advanced/network.md @@ -155,13 +155,10 @@ It allows network switches to learn where traffic should be routed to. It can be thought of like an IP address but statically assigned to hardware and only relevant within your local network. Much like IP addresses, MAC addresses have to be unique for the network to function properly, -but unlike IP addresses, they cannot be dynamically assigned by a DHCP server, MAC addresses are static by design. -Most vendors work around this problem by shipping their products with a random MAC address from the factory. -The idea being the sheer number of MAC addresses being randomly assigned -means the chance of the same MAC address being used in the same local network and causing a conflict is very low. +but unlike IP addresses, they cannot be dynamically assigned by a DHCP server, MAC addresses are static by design. -Some operating systems like [Mr Fusion](../setup/software.md#flash-mr-fusion-to-your-microsd) -will randomize the MiSTers MAC address during setup while other installers will use the same MAC address everytime. +Some installers like [Mr Fusion](../setup/software.md#flash-mr-fusion-to-your-microsd) +will randomize the MiSTers MAC address during setup, but others will use the same MAC address everytime. Therefore, it is common that two or more MiSTers will have the exact same MAC address on their onboard ethernet port. If two MiSTers with the same MAC address are on the same network at the same time, @@ -172,52 +169,24 @@ Fortunately, if this is the case, it's possible to override the default MAC addr From the MiSTers startup menu, press ++F9++ to get a Linux terminal then login as root (see [Network Access](#network-access) for the default credentials). -#### Check MAC address -Remove the cord from your MiSTers built-in ethernet if there is one attached -then run the command `ip link` by typing it and pressing ++Enter++. -You should get a result somewhat like this: +#### Change MAC address +Open u-boot.txt file for editing by running the command `nano /media/fat/linux/u-boot.txt` +by typing it and pressing ++Enter++. +The file should contain a line that looks somewhat like this: ``` -1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 -2: eth0: mtu 1500 qdisc mq state DOWN mode DEFAULT group default qlen 1000 - link/ether 02:03:04:05:06:07 brd ff:ff:ff:ff:ff:ff permaddr 02:03:04:05:06:07 -``` -`eth0` should be the built-in ethernet on the DE-10 nano while `link/ether` is the currently assigned MAC address -and `permaddr` is the hardware default MAC address if no other is given. - -Repeat these first two steps on all you MiSTers and continue on each one that has the same `link/ether` as another. - -#### Override MAC address -> Let's assume you want the network interface named `eth0` to be assigned a MAC address of `01:02:03:04:05:06`. -Replace these values with the conflicting network interface name you saw in the previous step -and the MAC address you want to set it to. -You can choose any MAC address you like, so long as it is **not** used by **any** other device. -> -> A valid MAC address is six sets of two digits between `01` and `fe` each seperated by a `:` character. - -Run the command `nano /etc/dhcpcd.enter-hook` to edit or create the file then write the following -``` -if [ "$interface" = "eth0" ]; then - ip link set dev "$interface" address 01:02:03:04:05:06 -fi +ethaddr=EA:C8:21:56:E3:43 ``` -Once done, press ++Ctrl+o++ to make `nano` save `dhcpcd.enter-hook` then ++Ctrl+x++ to exit `nano`. -Run the command `reboot` to restart the MiSTer back to the startup menu with the new network settings applied. +Edit the MAC address so that no MiSTers on your network share the same address. +MAC addresses are made up of six sets of two characters that range between `00`-`FF` and are seperated by `:`. +When changing the MAC address, avoid these addresses that have special meaning: -#### Verify the new MAC address applied -Login to root on the Linux terminal the same way you did before and run the command `ip link` again. -You should get a result somewhat like this: -``` -1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000 - link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 -2: eth0: mtu 1500 qdisc mq state DOWN mode DEFAULT group default qlen 1000 - link/ether 01:02:03:04:05:06 brd ff:ff:ff:ff:ff:ff permaddr 02:03:04:05:06:07 -``` -`link/ether` should be the same MAC address you set in `/etc/dhcpcd.enter-hook`. -If it is, you can now reattach the cord to this MiSTers built-in ethernet. -In the unlikely event that the new MAC address you chose conflicts with another device on your network -then replace that MAC address in `dhcpcd.enter-hook` with another random MAC address and `reboot` again. +* Any address that start's with `00`, `01`, `02`, `03`, `06` or `0A` +* Broadcast (`FF:FF:FF:FF:FF:FF`) +* All zeros (`00:00:00:00:00:00`) + +Once done, press ++Ctrl+o++ to make `nano` save `u-boot.txt` then ++Ctrl+x++ to exit `nano` then +run the command `reboot` to restart the MiSTer back to the startup menu with the new MAC address applied. ### Hostname configuration `dhcpcd` can be configured so that MiSTer offers its preferred name to your DHCP server, but it's disabled by default.