Make orbic-network the default, update documentation, add deprecation warnings

doc/installing-from-release-windows.md

@@ -1,39 +0,0 @@
-# Installing from the latest release (Windows)
-
-Windows support in Rayhunter's installer is a work-in-progress. Depending on the device, the installation instructions differ.
-
-## TP-Link
-
-1. Insert a FAT-formatted SD card. This will be used to store all recordings.
-2. Connect the device via WiFi or USB Tethering -- you should be able to view the TP-Link admin page on <http://192.168.0.1>.
-3. Download the latest release (must be at least 0.3.0) for windows-x86_64, and unpack the zipfile.
-4. Open PowerShell or CMD in that extracted folder, the installer: `./installer tplink`
-5. Follow the instructions on the screen, if there are any.
-
-## Orbic
-
-<div class=warning><strong>
-
-[The Windows USB installer is known to be buggy](https://github.com/EFForg/rayhunter/issues/366). We strongly recommend using the [Network-based installer](./orbic.md#the-network-installer).
-
-</strong></div>
-
-1. Connect the device to your computer using the provided USB cable.
-1. Install the [Zadig WinUSB driver installer](https://zadig.akeo.ie/).
-1. Open Zadig, click options->show all devices 
-
-    ![Zadig](./zadig2.png)
-
-1. Select 'RNDIS (Interface 0)'
-
-    ![Zadig](./zadig.png)
-
-1. Click 'install driver' and wait for it to finish. 
-2. Download the latest `rayhunter-vX.X.X-windows-x86_64.zip` from the [Rayhunter releases page](https://github.com/EFForg/rayhunter/releases). The version you download will have numbers instead of X
-3. Unzip `rayhunter-vX.X.X-windows-x86_64` .
-1. Open a powershell terminal by pressing Win+R and typing `powershell` and hitting enter. 
-5. Type `cd ~\Downloads\rayhunter-v<x.x.x>-windows-x86_64` (**Replace <x.x.x> with the Rayhunter version you just unzipped**) and hit enter.
-5. Run the install script: `.\installer.exe orbic` and hit enter.
-    - The device will restart multiple times over the next few minutes.
-    - You will know it is done when you see terminal output that says `checking for rayhunter server...success!`
-6. Rayhunter should now be running! You can verify this by following the instructions below to [view the web UI](./using-rayhunter.md#the-web-ui). You should also see a green line flash along the top of top the display on the device.

doc/installing-from-release.md

@@ -2,7 +2,7 @@
 
 Make sure you've got one of Rayhunter's [supported devices](./supported-devices.md). These instructions have only been tested on macOS and Ubuntu 24.04. If they fail, you will need to [install Rayhunter from source](./installing-from-source.md).
 
-1. For the TP-Link only, insert a FAT-formatted SD card. This will be used to store all recordings.
+1. **For the TP-Link only,** insert a FAT-formatted SD card. This will be used to store all recordings.
 2. Download the latest `rayhunter-vX.X.X-PLATFORM.zip` from the [Rayhunter releases page](https://github.com/EFForg/rayhunter/releases) for your platform:
     - for Linux on x64 architecture: `linux-x64`
     - for Linux on ARM64 architecture: `linux-aarch64`
@@ -18,29 +18,48 @@ Make sure you've got one of Rayhunter's [supported devices](./supported-devices.
     cd ~/Downloads/rayhunter-vX.X.X-PLATFORM
     ```
 
-4. Turn on your device by holding the power button on the front.
+   On Windows you can decompress using the file browser, then navigate to the
+   folder that contains `installer.exe`, **hold Shift**, Right-Click inside the
+   folder, then click "Open in PowerShell".
 
-   * For the Orbic, connect the device using a USB-C cable.
-     * Or connect to the network if using the network based installer, this is especially recommended on Windows.
-   * For TP-Link, connect to its network using either WiFi or USB Tethering.
+4. **Connect to your device.**
 
-5. Run the installer:
+   First turn on your device by holding the power button on the front.
 
-    ```bash
-    # On MacOS, you must first remove the quarantine bit
-    xattr -d com.apple.quarantine installer
-    ```
-    Then run the installer:
-    ```bash
-    ./installer orbic
-    # or: ./installer [orbic-network|tplink|tmobile|uz801|pinephone|wingtech]
-    ```
+   Then connect to the device using either WiFi or USB tethering.
 
-    The device will restart multiple times over the next few minutes.
+   You know you are in the right network when you can access
+   <http://192.168.1.1> (Orbic) or <http://192.168.0.1> (TP-Link) and see the
+   hardware's own admin menu.
 
-    You will know it is done when you see terminal output that says `Testing Rayhunter... done`
+5. **On MacOS only**, you have to run `xattr -d
+   com.apple.quarantine installer` to allow execution of
+   the binary.
 
-6. Rayhunter should now be running! You can verify this by [viewing Rayhunter's web UI](./using-rayhunter.md). You should also see a green line flash along the top of top the display on the device.
+6. **Run the installer.**
+
+   ```bash
+   # For Orbic:
+   ./installer orbic --admin-password 'mypassword'
+
+   # For TP-Link:
+   ./installer tplink
+   ```
+
+   * On Verizon Orbic, the password is the WiFi password.
+   * On Kajeet/Smartspot devices, the default password is `$m@rt$p0tc0nf!g`
+   * On Moxee-brand devices, check under the battery for the password.
+   * You can reset the password by pressing the button under the back case until the unit restarts.
+
+   TP-Link does not require an `--admin-password` parameter.
+
+   For other devices, check `./installer --help` or the
+   respective page in the sidebar under "Supported
+   Devices."
+
+7. The installer will eventually tell you it's done, and the device will reboot.
+
+8. Rayhunter should now be running! You can verify this by [viewing Rayhunter's web UI](./using-rayhunter.md). You should also see a green line flash along the top of top the display on the device.
 
 ## Troubleshooting
 

doc/orbic.md

@@ -21,6 +21,22 @@ or on [eBay](https://www.ebay.com/sch/i.html?_nkw=orbic+rc400l).
 | Wifi 5Ghz | a/ac/ax |
 | Wifi 6 | 🮱 |
 
+## Two kinds of installers
+
+The orbic's installation routine underwent many different changes:
+
+1. The ADB-based shellscript prior to version 0.3.0
+2. The Rust-based, ADB-based installer since version 0.3.0
+3. Then, starting with 0.6.0, an alternative installer `./installer
+   orbic-network` that is supposed to work more reliably, can run over the
+   Orbic's WiFi connection and without the need to manually install USB drivers
+   on Windows.
+4. Starting with 0.8.0, `orbic-network` has been renamed to `orbic`, and the
+   old `./installer orbic` is now called `./installer orbic-usb`.
+   
+It's possible that many tutorials out there still refer to some of the old
+installation routines.
+
 ## The Network Installer
 
 Since Rayhunter 0.6.0 there is an alternative, experimental installation
@@ -43,8 +59,11 @@ The drawback is that the device's admin password is required.
 
 ## Obtaining a shell
 
-After running through the installation procedure, you can obtain a root shell
-by running `adb shell` or `./installer util shell`. Then, inside of that shell
-you can run `/bin/rootshell` to obtain "fakeroot."
+After running the installer, there will not be a rootshell and ADB will not be
+enabled. Instead you can use `./installer util orbic-start-telnet` and connect
+to the hotspot using `nc 192.168.1.1 24`. On Windows you might not have `nc`
+and will have to use WSL for that.
 
-If you are using the network installer, there will not be a rootshell and ADB will not be enabled by the installer. Instead you can use `./installer util orbic-start-telnet` and connect to the hotspot using `nc 192.168.1.1 24`. On Windows you might not have `nc` and will have to use WSL for that.
+If you are using an installer prior to 0.7.0 or `orbic-usb` explicitly, you can
+obtain a root shell by running `adb shell` or `./installer util shell`. Then,
+inside of that shell you can run `/bin/rootshell` to obtain "fakeroot."

installer/src/main.rs

@@ -26,12 +26,11 @@ struct Args {
 // of the manufacturer's capitalisation.
 #[derive(Subcommand, Debug)]
 enum Command {
-    /// Install rayhunter on the Orbic Orbic RC400L.
-    Orbic(InstallOrbic),
+    /// Install rayhunter on the Orbic RC400L using the legacy USB+ADB-based installer.
+    OrbicUsb(InstallOrbic),
     /// Install rayhunter on the Orbic RC400L or Moxee Hotspot via network.
-    ///
-    /// This is an experimental installer for Orbic that does not require USB drivers on Windows.
-    OrbicNetwork(OrbicNetworkArgs),
+    #[clap(alias = "orbic-network")]
+    Orbic(OrbicNetworkArgs),
     /// Install rayhunter on the TMobile TMOHS1.
     Tmobile(TmobileArgs),
     /// Install rayhunter on the Uz801.
@@ -84,7 +83,7 @@ struct OrbicNetworkArgs {
 
     /// Admin password for authentication.
     #[arg(long)]
-    admin_password: String,
+    admin_password: Option<String>,
 }
 
 #[derive(Parser, Debug)]
@@ -207,8 +206,8 @@ async fn run() -> Result<(), Error> {
         Command::Tplink(tplink) => tplink::main_tplink(tplink).await.context("Failed to install rayhunter on the TP-Link M7350. Make sure your computer is connected to the hotspot using USB tethering or WiFi.")?,
         Command::Pinephone(_) => pinephone::install().await
             .context("Failed to install rayhunter on the Pinephone's Quectel modem")?,
-        Command::Orbic(_) => orbic::install().await.context("\nFailed to install rayhunter on the Orbic RC400L")?,
-        Command::OrbicNetwork(args) => orbic_network::install(args.admin_ip, args.admin_username, args.admin_password).await.context("\nFailed to install rayhunter on the Orbic RC400L via network exploit")?,
+        Command::OrbicUsb(_) => orbic::install().await.context("\nFailed to install rayhunter on the Orbic RC400L (USB installer)")?,
+        Command::Orbic(args) => orbic_network::install(args.admin_ip, args.admin_username, args.admin_password).await.context("\nFailed to install rayhunter on the Orbic RC400L")?,
         Command::Wingtech(args) => wingtech::install(args).await.context("\nFailed to install rayhunter on the Wingtech CT2MHS01")?,
         Command::Util(subcommand) => match subcommand.command {
             UtilSubCommand::Serial(serial_cmd) => {
@@ -246,7 +245,7 @@ async fn run() -> Result<(), Error> {
             UtilSubCommand::WingtechStartAdb(args) => wingtech::start_adb(&args.admin_ip, &args.admin_password).await.context("\nFailed to start adb on the Wingtech CT2MHS01")?,
             UtilSubCommand::PinephoneStartAdb => pinephone::start_adb().await.context("\nFailed to start adb on the PinePhone's modem")?,
             UtilSubCommand::PinephoneStopAdb => pinephone::stop_adb().await.context("\nFailed to stop adb on the PinePhone's modem")?,
-            UtilSubCommand::OrbicStartTelnet(args) => orbic_network::start_telnet(&args.admin_ip, &args.admin_username, &args.admin_password).await.context("\\nFailed to start telnet on the Orbic RC400L")?,
+            UtilSubCommand::OrbicStartTelnet(args) => orbic_network::start_telnet(&args.admin_ip, &args.admin_username, args.admin_password.as_deref()).await.context("\\nFailed to start telnet on the Orbic RC400L")?,
         }
     }
 

installer/src/orbic.rs

@@ -61,6 +61,10 @@ async fn confirm() -> Result<bool> {
 }
 
 pub async fn install() -> Result<()> {
+    println!(
+        "WARNING: The orbic USB installer is likely to go away in a future version of Rayhunter. Consider using ./installer orbic instead."
+    );
+
     #[cfg(target_os = "windows")]
     {
         let confirmation = confirm().await?;
@@ -84,6 +88,10 @@ pub async fn install() -> Result<()> {
 }
 
 pub async fn shell() -> Result<()> {
+    println!(
+        "WARNING: The orbic USB installer is likely to go away in a future version of Rayhunter. Consider using ./installer util orbic-start-telnet instead."
+    );
+
     println!("opening shell");
     let mut adb_device = get_adb().await?;
     adb_device.shell(&mut std::io::stdin(), Box::new(std::io::stdout()))?;

installer/src/orbic_network.rs

@@ -122,8 +122,12 @@ async fn login_and_exploit(admin_ip: &str, username: &str, password: &str) -> Re
 pub async fn start_telnet(
     admin_ip: &str,
     admin_username: &str,
-    admin_password: &str,
+    admin_password: Option<&str>,
 ) -> Result<()> {
+    let Some(admin_password) = admin_password else {
+        anyhow::bail!("--admin-password is required");
+    };
+
     echo!("Logging in and starting telnet... ");
     login_and_exploit(admin_ip, admin_username, admin_password).await?;
     println!("done");
@@ -134,8 +138,22 @@ pub async fn start_telnet(
 pub async fn install(
     admin_ip: String,
     admin_username: String,
-    admin_password: String,
+    admin_password: Option<String>,
 ) -> Result<()> {
+    let Some(admin_password) = admin_password else {
+        eprintln!(
+            "As of version 0.8.0, the orbic installer has been rewritten and now requires an --admin-password parameter."
+        );
+        eprintln!(
+            "Refer to the official documentation at https://efforg.github.io/rayhunter/ for how to find the right value."
+        );
+        eprintln!();
+        eprintln!(
+            "If you are following a tutorial that does not include this parameter, the tutorial is likely outdated. You can run ./installer orbic-usb to access the old installer, however we recommend against it."
+        );
+        anyhow::bail!("exiting");
+    };
+
     echo!("Logging in and starting telnet... ");
     login_and_exploit(&admin_ip, &admin_username, &admin_password).await?;
     println!("done");