doc/md/Installation_Instructions/ModemManager-Must-Be-Discarded.md

   1 # If you're a Linux user
   2
   3 ModemManager is a real threat that can lead to a bricked Proxmark3, read this very attentively.
   4
   5 **The problem:**
   6
   7 ModemManager is pre-installed on many different Linux distributions, very probably yours as well.
   8 It's intended to prepare and configure the mobile broadband (2G/3G/4G) devices, whether they are built-in or dongles.
   9 Some are serial, so when the Proxmark3 is plugged and a `/dev/ttyACM0` appears, ModemManager attempts to talk to it to see if it's a modem replying to AT commands.
  10
  11 Now imagine what happens when you're flashing your Proxmark3 and ModemManager suddenly starts sending bytes to it at the same time...
  12 Yes it makes the flashing failing. And if it happens while you're flashing the bootloader, it will require a JTAG device to unbrick the Proxmark3.
  13
  14 ModemManager is a threat for the Proxmark3, but also for many other embedded devices, such as some Arduino platforms.
  15
  16 # Solution 1: remove ModemManager
  17
  18 If you don't need ModemManager, the safest is to remove it entirely.
  19
  20 On Debian-alike (Ubuntu, Kali,...):
  21 ```sh
  22 sudo apt remove modemmanager
  23 ```
  24 On Archlinux:
  25 ```sh
  26 sudo pacman -R modemmanager
  27 ```
  28
  29 # Solution 2: disable ModemManager
  30
  31 ```sh
  32 sudo systemctl stop ModemManager
  33 sudo systemctl disable ModemManager
  34 ```
  35
  36 # Solution 3: use filtering udev rules
  37
  38 If you *really* need ModemManager, e.g. for your 4G device, you'll have to use some filtering rules to make sure it doesn't interfere with the Proxmark3.
  39
  40 Once you have cloned the Proxmark3 repository, you can run `make udev` to install udev rules that will tell ModemManager to not look at your Proxmark3.
  41
  42 **BEWARE** it will not work if your ModemManager installation is using a `strict` policy, which is the case on some distributions.
  43 So you'll need first to check what `filter-policy` is used on your distribution:
  44
  45 ```sh
  46 systemctl status ModemManager
  47 ```
  48 ```
  49 ● ModemManager.service - Modem Manager
  50    Loaded: loaded (/lib/systemd/system/ModemManager.service...
  51    Active: active (running) since ...
  52    ...
  53    CGroup: /system.slice/ModemManager.service
  54            └─XXXX /usr/sbin/ModemManager --filter-policy=strict
  55 ```
  56
  57 If it's using `filter-policy=strict`, either look at [solution 4](#solution-4-use-global-ttyACM-filtering-rule) or change the filter policy of your system.
  58
  59 In any case, it's very important that you test if the filtering is effective before attempting to flash your Proxmark3, see section [Testing ModemManager filtering effectiveness](#Testing-ModemManager-filtering-effectiveness).
  60
  61 # Solution 4: use global ttyACM filtering rule
  62
  63 Edit the system ModemManager configuration:
  64 ```sh
  65 sudo systemctl edit ModemManager.service
  66 ```
  67 And add the following content to add a global ttyACM filtering rule:
  68 ```
  69 [Service]
  70 Environment="MM_FILTER_RULE_TTY_ACM_INTERFACE=0"
  71 ```
  72 This will create the following file: `/etc/systemd/system/ModemManager.service.d/override.conf`. Then restart the service:
  73 ```sh
  74 sudo service ModemManager restart
  75 ```
  76
  77 It's very important that you test if the filtering is effective before attempting to flash your Proxmark3, see section [Testing ModemManager filtering effectiveness](#Testing-ModemManager-filtering-effectiveness).
  78
  79 # Testing ModemManager filtering effectiveness
  80
  81 If you chose to keep ModemManager, test the filtering effectiveness before attempting to flash Proxmark3.
  82
  83 **Reboot**
  84
  85 Turn systemd debug on and watch logs:
  86 ```sh
  87 sudo mmcli -G DEBUG
  88 sudo journalctl -f|grep "ModemManager.*\[filter\]"
  89 ```
  90 Now plug in the Proxmark 3.
  91
  92 If ModemManager interferes, you'll get logs like this:
  93 ```
  94 ModemManager[xxxxx]: <debug> [filter] (tty/ttyACM0): port allowed: cdc-acm interface reported AT-capable
  95 ```
  96 It it's the case, you *need to fix your ModemManager issues* before using the Proxmark3.
  97
  98 When ModemManager is properly filtering `/dev/ttyACM0`:
  99 ```
 100 ModemManager[xxxxx]: <debug> [filter] (tty/ttyACM0) port filtered: forbidden
 101 ```
 102 If this is the case, you're fine and you can safely use and flash the PRoxmark3 on your system.
 103
 104 To turn systemd debug off again:
 105 ```sh
 106 sudo mmcli -G ERR
 107 ```
 108
 109 # I didn't read carefully this page and now my Proxmark3 is not responding
 110
 111 First of all, follow the instructions above to make sure ModemManager will not interfere with the Proxmark3 anymore.
 112
 113 Now there are two possibilities:
 114
 115 ## Only the fullimage is damaged
 116
 117 If the flashing of the fullimage failed, you can still force the Proxmark to start in bootloader mode by keeping the button pressed while you're plugging it in and while you're attempting to flash it again.
 118
 119 In short:
 120
 121 * unplug device
 122 * press button and keep it pressed (IMPORTANT)
 123 * plug in device
 124 * run flash command `pm3-flash-fullimage`
 125 * wait until flash is finished
 126 * release button
 127 * un/plug device
 128
 129 ## The bootloader is damaged
 130
 131 If attempting to flash via the button fails, this means your bootloader is corrupted.
 132 You'll have no other choice than flashing it via an external JTAG instrument.