Add 3DS setup instructions

.gitignore

@@ -6,3 +6,6 @@
 
 # Log files
 /logs/
+
+# Mitmproxy CA certificate
+/console-files/mitmproxy-ca-cert.pem

README.md

@@ -37,7 +37,7 @@ Everything else runs inside Docker containers.
 | ------------- | ---------------------------- |
 | Wii U         | ✅ Working                   |
 | Cemu emulator | ❓ Untested                  |
-| 3DS           | ❓ Untested                  |
+| 3DS           | ✅ Working                   |
 | Switch        | ❌ Not supported by Pretendo |
 
 ## Usage
@@ -127,12 +127,22 @@ line and have a basic understanding of Docker.
    Juxt posts.
 4. Go back to [after creating a PNID](#after-creating-a-pnid).
 
+#### Changing which server you are connected to (Web)
+
+- To connect to your selfhosted Pretendo server, create a shortcut to your web
+  browser with the proxy settings and use that to open the Pretendo Network
+  website.
+- To connect to the official Pretendo servers, use your regular web browser
+  without the proxy settings.
+
 ### Wii U
 
 1. Follow the
    [official Pretendo Network installation guide](https://pretendo.network/docs/install/wiiu)
    to install the patches. At this point, you should be connected to the
-   official Pretendo Network servers. **Don't create a new PNID yet.**
+   official Pretendo Network servers. **You may create a new PNID on the
+   official servers now if you wish.** If you do so, come back to this guide
+   when you are done.
 2. Open System Settings => Internet => Connect to the Internet => Connections =>
    (Your current internet connection) => Change Settings.
 3. Go to DNS => Don't Auto-obtain => (Set both the primary and secondary DNS to
@@ -170,7 +180,77 @@ line and have a basic understanding of Docker.
 
 ### 3DS
 
-- Currently untested
+> **Warning:** Due to the 3DS's account system, using a local Pretendo Network
+> server with it requires some potentially dangerous modifications to the
+> CTRNAND. **Create a NAND backup before proceeding.**
+
+1. Follow the
+   [official Pretendo Network installation guide](https://pretendo.network/docs/install/3ds)
+   to install the patches. At this point, you should be connected to the
+   official Pretendo Network servers. Linking your official PNID in System
+   Settings is optional.
+2. Open System Settings => Internet Settings => Connection Settings => (Your
+   current connection) => Change Settings.
+3. Go to DNS => No => Detailed Setup => (Set both the primary and secondary DNS
+   to your server's IP address) => OK.
+4. Go to Proxy Settings => Yes => Detailed Setup => (Set the proxy server to
+   your server's IP address and the port to 8080) => OK => Don't Use
+   Authentication.
+5. Save the settings and go back to the Home Menu. Check your mitmproxy logs at
+   <http://127.0.0.1:8081> to verify that the console is sending HTTP requests
+   through your proxy.
+   - If you open the Friends List now, you might get a message that "This
+     device's access to online services has been restricted by Nintendo." **Your
+     3DS is not banned. This is expected.** Your 3DS is trying to log into your
+     local Pretendo server using a NEX account that doesn't exist in the
+     server's database.
+6. Start ftpd on your console and run `./scripts/upload-3ds-files.sh` to upload
+   the required files to your console.
+7. **This is the potentially dangerous part that modifies your CTRNAND.** As the
+   official Pretendo docs explain, Nimbus works by setting up a second Friends
+   account using a test environment instead of prod. On the first run, it
+   creates this account, and on subsequent runs, it switches to the
+   already-existing one. Unfortunately, you cannot create a third test account,
+   but what you _can_ do is back up the save data for the Friends and account
+   system modules and then reset the test account.
+   [Trace](https://github.com/TraceEntertains) (`traceentertains` on Discord)
+   created a modified version of Nimbus that resets the Friends test
+   environment, and I created a GodMode9 script to automate save backups and
+   switching save slots for the system modules.
+   > **All credit for the Friends test account reset program** (originally
+   > released on the Pretendo Network Discord server as
+   > "`manual_override.3dsx`") **goes to Trace.**
+   1. Reboot into GodMode9 and open the scripts menu.
+   2. Run the `FriendsSaveSwitcher` script and select "Save new slot". Name the
+      slot something descriptive like "pretendo_official".
+   3. Reboot into the Home Menu and open the Homebrew Launcher. From there, run
+      the `ResetFriendsTestAccount.3dsx` program.
+   4. Reboot into GodMode9 and open the scripts menu again.
+   5. Run the `FriendsSaveSwitcher` script and select "Save new slot" again.
+      Name the slot something descriptive like "local_server".
+   6. You now have multiple test Friends accounts saved on your SD card at
+      `sd:/gm9/out/friends_accounts/`. You can switch between them by running
+      the `FriendsSaveSwitcher` script, selecting "Load save slot", and
+      following the instructions (it's not very user-friendly yet).
+8. Open System Settings using your local server Friends test account and create
+   a new local PNID or sign in to one you created on a Wii U or website.
+
+#### Changing which server you are connected to (3DS)
+
+- To connect to your selfhosted Pretendo server:
+  - Use the custom mitmproxy certificate for Juxt by running
+    `./scripts/upload-3ds-files.sh`.
+  - Enable the custom DNS and proxy settings on the console.
+  - Switch to your local server Friends account by running the
+    `FriendsSaveSwitcher` script in GodMode9.
+- To connect to the official Pretendo servers:
+  - Use the official certificate for Juxt by running
+    `./scripts/upload-3ds-files.sh --reset`
+  - Disable the custom DNS and proxy settings on the console.
+  - Switch to your official Pretendo Friends account by running the
+    `FriendsSaveSwitcher` script in GodMode9.
+- To connect to Nintendo's servers, use Nimbus to switch to Nintendo Network and
+  disable the proxy settings.
 
 ## Uninstalling
 

console-files/FriendsSaveSwitcher.gm9

@@ -0,0 +1,60 @@
+# Very basic GodMode9 script to create, back up, and switch between save slots
+# for the Friends and account (NNID) system modules
+# Reference: https://3dbrew.org/wiki/System_SaveData
+
+set friends_save_data "1:/data/$[SYSID0]/sysdata/00010032/00000000"
+set account_save_data "1:/data/$[SYSID0]/sysdata/00010038/00000000"
+set save_slots_dir "$[GM9OUT]/friends_accounts"
+set current_save_file "$[save_slots_dir]/current_save.txt"
+
+labelsel "What do you want to do?" "menu_*"
+
+
+# Save the current Friends and account system modules save data to a new slot
+@menu_Save_new_slot
+
+echo "This script will save your current Friends and\naccount save data to a new save slot on your\nSD card at $[save_slots_dir]"
+input "What do you want to name your new save slot?" new_save_slot_name
+
+# Copy the current Friends and account saves to the new save slot
+set output_save_dir "$[save_slots_dir]/$[new_save_slot_name]"
+cp "$[friends_save_data]" "$[output_save_dir]/friends.bin"
+cp "$[account_save_data]" "$[output_save_dir]/account.bin"
+
+# Save the name of the current save slot
+dumptxt "$[current_save_file]" "$[output_save_dir]"
+echo "Successfully saved your current save data to\n$[output_save_dir]"
+
+goto end
+
+
+# Load a previously-saved Friends and account system modules save slot
+@menu_Load_save_slot
+
+# Save the old save data to the current save slot
+# I can't figure out how to read the file using fget, so just ask the user to
+# choose when saving the current slot before switching
+echo "This script will load your Friends and account\nsave data from a previously saved slot.\nFirst, select a slot to save your current data."
+echo "The next screen displays the last loaded slot.\nSave your current data to this slot\nbefore loading a different one."
+textview "$[current_save_file]"
+dirsel "Which save slot do you want to save to?" "$[save_slots_dir]" save_slot_save
+ask "Overwrite this save slot?\n$[save_slot_save]"
+cp -w "$[friends_save_data]" "$[save_slot_save]/friends.bin"
+cp -w "$[account_save_data]" "$[save_slot_save]/account.bin"
+
+# Load a new save slot
+allow "$[friends_save_data]"
+allow "$[account_save_data]"
+dirsel "Which save slot do you want to load?" "$[save_slots_dir]" save_slot_load
+cp -w -n "$[save_slot_load]/friends.bin" "$[friends_save_data]"
+cp -w -n "$[save_slot_load]/account.bin" "$[account_save_data]"
+
+# Save the name of the loaded save slot
+dumptxt "$[current_save_file]" "$[save_slot_load]"
+echo "Successfully loaded the save slot\n$[save_slot_load]"
+
+goto end
+
+
+@end
+# Exit the script

console-files/juxt-prod.pem

@@ -0,0 +1,21 @@
+-----BEGIN CERTIFICATE-----
+MIIDdTCCAl2gAwIBAgILBAAAAAABFUtaw5QwDQYJKoZIhvcNAQEFBQAwVzELMAkG
+A1UEBhMCQkUxGTAXBgNVBAoTEEdsb2JhbFNpZ24gbnYtc2ExEDAOBgNVBAsTB1Jv
+b3QgQ0ExGzAZBgNVBAMTEkdsb2JhbFNpZ24gUm9vdCBDQTAeFw05ODA5MDExMjAw
+MDBaFw0yODAxMjgxMjAwMDBaMFcxCzAJBgNVBAYTAkJFMRkwFwYDVQQKExBHbG9i
+YWxTaWduIG52LXNhMRAwDgYDVQQLEwdSb290IENBMRswGQYDVQQDExJHbG9iYWxT
+aWduIFJvb3QgQ0EwggEiMA0GCSqGSIb3DQEBAQUAA4IBDwAwggEKAoIBAQDaDuaZ
+jc6j40+Kfvvxi4Mla+pIH/EqsLmVEQS98GPR4mdmzxzdzxtIK+6NiY6arymAZavp
+xy0Sy6scTHAHoT0KMM0VjU/43dSMUBUc71DuxC73/OlS8pF94G3VNTCOXkNz8kHp
+1Wrjsok6Vjk4bwY8iGlbKk3Fp1S4bInMm/k8yuX9ifUSPJJ4ltbcdG6TRGHRjcdG
+snUOhugZitVtbNV4FpWi6cgKOOvyJBNPc1STE4U6G7weNLWLBYy5d4ux2x8gkasJ
+U26Qzns3dLlwR5EiUWMWea6xrkEmCMgZK9FGqkjWZCrXgzT/LCrBbBlDSgeF59N8
+9iFo7+ryUp9/k5DPAgMBAAGjQjBAMA4GA1UdDwEB/wQEAwIBBjAPBgNVHRMBAf8E
+BTADAQH/MB0GA1UdDgQWBBRge2YaRQ2XyolQL30EzTSo//z9SzANBgkqhkiG9w0B
+AQUFAAOCAQEA1nPnfE920I2/7LqivjTFKDK1fPxsnCwrvQmeU79rXqoRSLblCKOz
+yj1hTdNGCbM+w6DjY1Ub8rrvrTnhQ7k4o+YviiY776BQVvnGCv04zcQLcFGUl5gE
+38NflNUVyRRBnMRddWQVDf9VMOyGj/8N7yy5Y0b2qvzfvGn9LhJIZJrglfCm7ymP
+AbEVtQwdpf5pLGkkeB6zpxxxYu7KyJesF12KwvhHhm4qxFYxldBniYUr+WymXUad
+DKqC5JlR3XC321Y9YeRq4VzW9v493kHMB65jUr9TU/Qr6cf9tveCX4XSQRjbgbME
+HMUfpIBvFSDJ3gyICh3WZlXi/EjJKSZp4A==
+-----END CERTIFICATE-----

scripts/README.md

@@ -38,3 +38,5 @@ administration. Here is a list of each one and what it does.
 - `update-postgres-password.sh`: This updates the password for the PostgreSQL
   database. It should be run whenever the password is regenerated, and it is
   automatically run by `setup-environment.sh`.
+- `upload-3ds-files.sh`: This uploads required files from `/console-files` to
+  your 3DS to help with setting it up to connect to your local server.

scripts/setup-environment.sh

@@ -14,7 +14,7 @@ generate_hex() {
 
 # Validate arguments
 if [ "$#" -lt 1 ]; then
-    echo "Usage: $0 <server IP address> [Wii U IP address]"
+    echo "Usage: $0 <server IP address> [Wii U IP address] [3DS IP address]"
     exit 1
 fi
 server_ip=$1
@@ -22,6 +22,10 @@ wiiu_ip=
 if [ "$#" -ge 2 ]; then
     wiiu_ip=$2
 fi
+ds_ip=
+if [ "$#" -ge 3 ]; then
+    ds_ip=$3
+fi
 
 git_base=$(git rev-parse --show-toplevel)
 . "$git_base/scripts/.function-lib.sh"
@@ -109,6 +113,14 @@ else
     info "Skipping Wii U IP address."
 fi
 
+# Get the 3DS IP address
+if [ -n "$ds_ip" ]; then
+    info "Using 3DS IP address $ds_ip."
+    echo "DS_IP=$ds_ip" >>./system.local.env
+else
+    info "Skipping 3DS IP address."
+fi
+
 # Create a list of important secrets
 cat >"$git_base/secrets.txt" <<EOF
 Pretendo Network server secrets
@@ -122,6 +134,7 @@ Postgres username: postgres_pretendo
 Postgres password: $postgres_password
 Server IP address: $server_ip
 Wii U IP address: ${wiiu_ip:-(not set)}
+3DS IP address: ${ds_ip:-(not set)}
 EOF
 
 success "Successfully set up environment."

scripts/upload-3ds-files.sh

@@ -0,0 +1,48 @@
+#! /bin/sh
+
+set -eu
+
+should_reset=false
+if [ "${1-}" = "--reset" ]; then
+    should_reset=true
+fi
+
+git_base=$(git rev-parse --show-toplevel)
+. "$git_base/scripts/.function-lib.sh"
+cd "$git_base"
+
+if [ ! -f "$git_base/environment/system.local.env" ]; then
+    error "Missing environment file system.local.env. Did you run setup-environment.sh?"
+    exit 1
+fi
+. "$git_base/environment/system.local.env"
+if [ -z "${DS_IP+x}" ]; then
+    warning "Missing environment variable DS_IP. Did you specify a 3DS IP address when you ran setup-environment.sh?"
+    info "Continuing without automatic FTP upload."
+fi
+
+if [ "$should_reset" = false ]; then
+    docker compose up -d mitmproxy-pretendo
+
+    while ! docker compose exec mitmproxy-pretendo ls /home/mitmproxy/.mitmproxy/mitmproxy-ca-cert.pem >/dev/null; do
+        info "Waiting for mitmproxy to generate a certificate..."
+        sleep 1
+    done
+
+    # Get the current certificate
+    docker compose cp mitmproxy-pretendo:/home/mitmproxy/.mitmproxy/mitmproxy-ca-cert.pem ./console-files/mitmproxy-ca-cert.pem
+else
+    info "Reset the Juxt certificate."
+fi
+
+# Upload the required files
+if [ -n "${DS_IP+x}" ]; then
+    if [ "$should_reset" = false ]; then
+        ftp -u "ftp://user:pass@$DS_IP:5000/3ds/juxt-prod.pem" ./console-files/mitmproxy-ca-cert.pem
+        ftp -u "ftp://user:pass@$DS_IP:5000/gm9/scripts/FriendsSaveSwitcher.gm9" ./console-files/FriendsSaveSwitcher.gm9
+        ftp -u "ftp://user:pass@$DS_IP:5000/3ds/ResetFriendsTestAccount.3dsx" ./console-files/ResetFriendsTestAccount.3dsx
+    else
+        ftp -u "ftp://user:pass@$DS_IP:5000/3ds/juxt-prod.pem" ./console-files/juxt-prod.pem
+    fi
+    success "Successfully uploaded the required files to your 3DS."
+fi

setup.sh

@@ -64,7 +64,9 @@ echo "Enter the IP address of your Pretendo Network server. It must be accessibl
 read -r server_ip
 echo "Enter the IP address of your Wii U (optional). It is only used for automatic FTP uploads of modified Inkay patches."
 read -r wiiu_ip
-./scripts/setup-environment.sh "$server_ip" "$wiiu_ip"
+echo "Enter the IP address of your 3DS (optional). It is only used for automatic FTP uploads."
+read -r ds_ip
+./scripts/setup-environment.sh "$server_ip" "$wiiu_ip" "$ds_ip"
 
 stage "Pulling Docker images."
 docker compose pull