From 61e53661639e31dda0565e73b1f7bbf8639b9f0f Mon Sep 17 00:00:00 2001 From: lucasrpatten Date: Mon, 13 Feb 2023 21:53:35 -0700 Subject: [PATCH] Typo Corrections and Markdown Standardization --- .gitignore | 1 + clients/build-yourself-contribution-guide.md | 6 +-- clients/desktop-app-installation.md | 6 +-- clients/dev/flutter/README.md | 6 +-- clients/dev/flutter/objectbox.md | 4 +- home/README.md | 4 +- private-api/README.md | 1 - private-api/building-and-contributing.md | 14 +++--- private-api/imcore-documentation.md | 18 +++++-- private-api/installation.md | 26 +++++----- .../cloudflare-with-a-custom-domain.md | 2 +- .../nginx-manual-setup.md | 40 ++++++++-------- .../nginx-proxy-manager.md | 6 +-- ...-on-unofficial-macs-for-the-private-api.md | 48 +++++++------------ ...g-macos-in-vmware-on-windows-full-guide.md | 22 +++++---- .../enabling-imessage-in-a-vm.md | 16 +++---- .../running-macos-in-docker.md | 16 +++---- .../port-forwarding-and-dynamic-dns.md | 2 +- 18 files changed, 118 insertions(+), 120 deletions(-) create mode 100644 .gitignore diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..600d2d3 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +.vscode \ No newline at end of file diff --git a/clients/build-yourself-contribution-guide.md b/clients/build-yourself-contribution-guide.md index 736e82a..aa79a81 100644 --- a/clients/build-yourself-contribution-guide.md +++ b/clients/build-yourself-contribution-guide.md @@ -45,9 +45,9 @@ Building yourself will cause you to lose the ability to insert GIFs from your ke 1. Install NuGet package manager 2. Go to Visual Studio Installer -> Modify Build Tools -> Individual Components and install the latest Windows 10 SDK -3. Run the following commands: +3. Run the following commands: - ``` + ```cmd flutter clean git reset @@ -77,7 +77,7 @@ Make sure you've completed [#pre-requisites](build-yourself-contribution-guide.m 4. Make your changes 5. Run the app using `flutter run` or the green play button at the top of your IDE 6. Test your changes -7. Commit and PR! +7. Commit and PR! Make sure you don't commit your changes to comment out `onContentCommit`. diff --git a/clients/desktop-app-installation.md b/clients/desktop-app-installation.md index 7bcf73d..aaf09bd 100644 --- a/clients/desktop-app-installation.md +++ b/clients/desktop-app-installation.md @@ -16,7 +16,7 @@ Github Releases Microsoft Store Download {% endembed %} -### Standalone Executable +### Standalone Executable (Windows) 1. Download `bluebubbles_standalone.exe` from GitHub releases (linked above) 2. Run the installer @@ -31,7 +31,7 @@ Microsoft Store Download BlueBubbles on Flathub {% endembed %} -### Standalone Executable +### Standalone Executable (Linux) 1. Download `bluebubbles_linux.zip` from GitHub Releases (linked above) 2. Unzip `bluebubbles_linux.zip` @@ -48,6 +48,6 @@ Note: You might need to install the following dependencies: You can use the following command: -``` +```bash sudo apt-get -y install libnotify-dev vlc libvlc-dev appindicator3-0.1 libappindicator3-dev ``` diff --git a/clients/dev/flutter/README.md b/clients/dev/flutter/README.md index 87eec46..7a03c46 100644 --- a/clients/dev/flutter/README.md +++ b/clients/dev/flutter/README.md @@ -6,13 +6,13 @@ Check the sidebar for all the documentation! **(WIP)** ## Flutter "Review" -As mentioned in [#why-flutter](../../#why-flutter "mention"), we chose Flutter over building something in React Native, or in Java itself. When deciding our framework, we never had full cross platform in mind, and rather we were focusing on the ease of development. While native Android would definitely provide the best overall user experience, we decided to make a small tradeoff on this aspect to utilize Flutter's ease of use, scaleability, and quick turnaround times. +As mentioned in [#why-flutter](../../#why-flutter "mention"), we chose Flutter over building something in React Native, or in Java itself. When deciding our framework, we never had full cross platform in mind, and rather we were focusing on the ease of development. While native Android would definitely provide the best overall user experience, we decided to make a small tradeoff on this aspect to utilize Flutter's ease of use, scalability, and quick turnaround times. ### What We Love -By far and away, the best thing about Flutter has to be the ease of development. Flutter layouting and UI is ridiculously easy to understand, and creating great UI is a simple task. We also really like Dart syntax, it makes code very readable and has a lot of great features to make coding easier. +By far and away, the best thing about Flutter has to be the ease of development. Flutter layout design and UI is ridiculously easy to understand, and creating great UI is a simple task. We also really like Dart syntax, it makes code very readable and has a lot of great features to make coding easier. -Pub has been a great package repo - There are so many high quality packages available to drop into your project and eliminate the need for a ton of boilerplate code. We use everything from small UI packages to larger state / framework / dependency mangement packages. +Pub has been a great package repo - There are so many high quality packages available to drop into your project and eliminate the need for a ton of boilerplate code. We use everything from small UI packages to larger state / framework / dependency management packages. There is definitely much more to like, but it isn't important to list all that here. diff --git a/clients/dev/flutter/objectbox.md b/clients/dev/flutter/objectbox.md index 0c122cc..c3f48d8 100644 --- a/clients/dev/flutter/objectbox.md +++ b/clients/dev/flutter/objectbox.md @@ -8,11 +8,11 @@ description: >- ## Intro -Initially, our app used the [`sqflite` ](https://pub.dev/packages/sqflite)package as our database (i.e. SQLite). The iMessage database on macOS is an SQLite database, so it made the most sense for our app to emulate the same structure (which it did, we copied the CREATE statements for each table and used them to build our own internal database). +Initially, our app used the [`sqflite`](https://pub.dev/packages/sqflite) package as our database (i.e. SQLite). The iMessage database on macOS is an SQLite database, so it made the most sense for our app to emulate the same structure (which it did, we copied the CREATE statements for each table and used them to build our own internal database). This worked well for the most part, but we hit a major roadblock when we decided to port our app to desktop platforms using Flutter and the [`sqflite_common_ffi`](https://pub.dev/packages/sqflite\_common\_ffi) package - The speeds decreased dramatically. A simple DB call could take upwards of 5-10 seconds, and this was causing significant delay for actions like loading chats, message threads, etc which should normally take up to 1 second. -As a result, we decided to look into alternative databases. We landed on two potential ones: [`sqlite3` ](https://pub.dev/packages/sqlite3)and [`objectbox`](https://pub.dev/packages/objectbox). We first tried `sqlite3` to avoid a huge migration of code, but it was the same issue - speeds were too slow on desktop. Then, we moved to `objectbox`. The speed issue was resolved, but we discovered a whole host of other issues that required some hacky workarounds and advanced Dart coding to resolve, and this page will discuss that in depth. +As a result, we decided to look into alternative databases. We landed on two potential ones: [`sqlite3`](https://pub.dev/packages/sqlite3) and [`objectbox`](https://pub.dev/packages/objectbox). We first tried `sqlite3` to avoid a huge migration of code, but it was the same issue - speeds were too slow on desktop. Then, we moved to `objectbox`. The speed issue was resolved, but we discovered a whole host of other issues that required some hacky workarounds and advanced Dart coding to resolve, and this page will discuss that in depth. ## Web Support diff --git a/home/README.md b/home/README.md index 1bddc13..9390cb9 100644 --- a/home/README.md +++ b/home/README.md @@ -4,9 +4,7 @@ description: Landing page for our documentation # BlueBubbles Documentation -![](.gitbook/assets/image.png) - - +![BlueBubbles On Phone and Desktop](.gitbook/assets/image.png) Hey there, and welcome to the BlueBubbles documentation! This will provide links to the main documentation, as well as quick links to popular BlueBubbles guides. diff --git a/private-api/README.md b/private-api/README.md index f9764ef..3364a21 100644 --- a/private-api/README.md +++ b/private-api/README.md @@ -34,4 +34,3 @@ The bundle supports both Intel and Apple Silicon Macs. {% hint style="warning" %} Apple Silicon currently requires using beta MacForge, which can be found [here.](https://github.com/MacEnhance/appcast/raw/master/Beta/MacForge/MacForge.1.2.0B1.zip) {% endhint %} - diff --git a/private-api/building-and-contributing.md b/private-api/building-and-contributing.md index 0635afc..007a40a 100644 --- a/private-api/building-and-contributing.md +++ b/private-api/building-and-contributing.md @@ -24,13 +24,13 @@ You do not need to pay the $100 fee for the Apple Developer account. As soon as 3. Once inside Xcode, make sure you are signed into your Apple Developer account. 4. Open the `BlueBubblesHelper` target window inside Xcode, and navigate to the signing tab. Set the Team dropdown to the result that comes up with your Apple ID. -![](<.gitbook/assets/image (1).png>) +![BlueBubblesHelper](<.gitbook/assets/image (1).png>) 1. Now, you are ready to build. Just hit the play button, and the built bundle file will automatically install in MacForge. The iMessage app will quit and re-open to synchronize the changes. ## Contributing -Hey there, and welcome! We are always eager to have new contributors working on our projects. First and foremost, we recommend joining our [Discord ](https://discord.gg/sccHbCgh)as that is the best place you can get in touch with the main developers to discuss new features, ideas, or changes you're planning to make. Now, on to the guide... +Hey there, and welcome! We are always eager to have new contributors working on our projects. First and foremost, we recommend joining our [Discord](https://discord.gg/sccHbCgh) as that is the best place you can get in touch with the main developers to discuss new features, ideas, or changes you're planning to make. Now, on to the guide... {% hint style="warning" %} The Helper Bundle is quite challenging to get a hang of. The reason for this is because none of the internal iMessage Framework methods are commented or documented in any way. The only reasonable method of development is to make educated guesses and brute-force until you find something that works. @@ -57,18 +57,18 @@ The Helper Bundle development is filled with some jargon that might appear confu ### Contribution Resources 1. [Tweak Development Wiki](https://iphonedev.wiki/index.php/Main\_Page) - if you are new to reverse engineering, this may be a helpful resource. -2. [w0lfschild macOS Headers ](https://github.com/w0lfschild/macOS\_headers)- pre-dumped headers for macOS Big Sur and up **only**. If you are developing for Catalina and under, you will need to dump headers on your own machine, using the next tool. -3. [Steve Nygard class-dump ](http://stevenygard.com/projects/class-dump/)- macOS 10 only, [freedomtan classdump-dyld ](https://github.com/freedomtan/classdump-dyld/)- macOS 11 only. +2. [w0lfschild macOS Headers](https://github.com/w0lfschild/macOS\_headers) - pre-dumped headers for macOS Big Sur and up **only**. If you are developing for Catalina and under, you will need to dump headers on your own machine, using the next tool. +3. [Steve Nygard class-dump](http://stevenygard.com/projects/class-dump/) - macOS 10 only, [freedomtan classdump-dyld](https://github.com/freedomtan/classdump-dyld/) - macOS 11 only. Currently there is no classdump tool that we know of which works on macOS Monterey. However, all Big Sur header files should work fine on Monterey machines. 4. [dyld\_shared\_cache\_util](https://lapcatsoftware.com/articles/bigsur.html) - open-source tool from Apple that also dumps headers on macOS 11. This has not been tested by any developers as of yet, but may be a good alternative to freedomtan's classdump-dyld fork. -5. [ZKSwizzle ](https://github.com/alexzielenski/ZKSwizzle)- this tool is already built into the bundle. You can use it to "intercept" Objective-C method calls and see what arguments are passed to them. +5. [ZKSwizzle](https://github.com/alexzielenski/ZKSwizzle) - this tool is already built into the bundle. You can use it to "intercept" Objective-C method calls and see what arguments are passed to them. ### Development Process The following will attempt to outline how our development process runs from start to finish when adding a new feature to the bundle. -1. Is the feature reasonable to implement and can we get it to work cross-platform with all clients? Will we be able to send the required data to the bundle from the server app? +1. Is the feature reasonable to implement and can we get it to work cross-platform with all clients? Will we be able to send the required data to the bundle from the server app? This step is important to ask yourself. Ultimately the bundle is meant to be a companion to the server and clients, since it can't be used as a standalone app. We have to make sure the feature is reasonable in scope and can actually be implemented on clients. @@ -80,7 +80,7 @@ The following will attempt to outline how our development process runs from star 4. Keep testing until you've got code that works! 3. By this point, you should have working code for your feature. Congrats! The next step is to make sure your code is clean, safe from exceptions, typed properly with correct arguments, and can send correctly-formatted data back to the server, when applicable. We encourage that you comment your code as well. 4. You probably only developed the integration inside the folder for your macOS version, whether that be `10` or `11+`. If the iMessage feature is not version-specific, we also need to add your code to the other folder's `BlueBubblesHelper.m` file. You have 2 options: - 1. Make a VM on your macOS device following the guide for the OS you need: [Big Sur ](https://travellingtechguy.blog/macos-big-sur-on-vmware-fusion-12/)or [Catalina](https://travellingtechguy.blog/vmware-dep/). We highly recommend using a burner Apple ID on these VMs just in case Apple has a bad mood when you make the VM. + 1. Make a VM on your macOS device following the guide for the OS you need: [Big Sur](https://travellingtechguy.blog/macos-big-sur-on-vmware-fusion-12/) or [Catalina](https://travellingtechguy.blog/vmware-dep/). We highly recommend using a burner Apple ID on these VMs just in case Apple has a bad mood when you make the VM. 2. Reach out to a main developer (Tanay has a Catalina and Monterey VM on his Big Sur Mac), and they can add / test your code on the other macOS folder. 5. Make a PR :) diff --git a/private-api/imcore-documentation.md b/private-api/imcore-documentation.md index d25d45b..e26e7ba 100644 --- a/private-api/imcore-documentation.md +++ b/private-api/imcore-documentation.md @@ -13,7 +13,7 @@ Chat objects are defined as `IMChat`, and we access these via a lookup by `guid` To do this, you'll want to add the `IMChatRegistry.h` header into your project. ```objectivec -// Retreive a IMChat instance from a given guid +// Retrieve a IMChat instance from a given guid // // Uses the chat registry to get an existing instance of a chat based on the chat guid +(IMChat *) getChat: (NSString *) guid { @@ -264,6 +264,7 @@ This is an asynchronous process in IMCore, so it requires the use of a completio {% tabs %} {% tab title="macOS 10 (no replies)" %} + ```objectivec // now we will deserialize the attributedBody if it exists NSDictionary *attributedDict = data[@"attributedBody"]; @@ -304,9 +305,11 @@ void (^createMessage)(NSAttributedString*, NSAttributedString*, NSString*, NSStr createMessage(attributedString, subjectAttributedString, effectId, nil); ``` + {% endtab %} {% tab title="macOS 11+ (replies)" %} + ```objectivec // now we will deserialize the attributedBody if it exists NSDictionary *attributedDict = data[@"attributedBody"]; @@ -374,6 +377,7 @@ if (data[@"selectedMessageGuid"] != [NSNull null] && [data[@"selectedMessageGuid createMessage(attributedString, subjectAttributedString, effectId, nil); }` ``` + {% endtab %} {% endtabs %} @@ -445,6 +449,7 @@ This function simply converts text based reaction types to their integer counter {% tabs %} {% tab title="macOS 10" %} + ```objectivec //Map the reaction type long long reactionLong = [BlueBubblesHelper parseReactionType:(data[@"reactionType"])]; @@ -476,6 +481,7 @@ long long reactionLong = [BlueBubblesHelper parseReactionType:(data[@"reactionTy } }]; ``` + {% endtab %} {% tab title="macOS 11+" %} @@ -567,6 +573,7 @@ long long reactionLong = [BlueBubblesHelper parseReactionType:(data[@"reactionTy ### Editing a Message {% code lineNumbers="true" %} + ```objectivec // get the chat IMChat *chat = [BlueBubblesHelper getChat: data[@"chatGuid"] :transaction]; @@ -577,9 +584,10 @@ IMChat *chat = [BlueBubblesHelper getChat: data[@"chatGuid"] :transaction]; NSMutableAttributedString *bcString = [[NSMutableAttributedString alloc] initWithString: data[@"backwardsCompatibilityMessage"]]; NSInteger index = data["@partIndex"]; // send the edit - [chat editMessage:(message) atPartIndex:(index) withNewPartText:(editedString) backwardCompatabilityText:(bcString)]; + [chat editMessage:(message) atPartIndex:(index) withNewPartText:(editedString) backwardCompatibilityText:(bcString)]; }]; ``` + {% endcode %} This one is fairly easy. The only tricky part is the part index, which corresponds to which part of a message is being edited. Sometimes, a message can be stacked as so: @@ -595,12 +603,13 @@ The part index tells IMCore which part of the message is actually being edited, ### Unsending a Message {% code lineNumbers="true" %} + ```objectivec // get the chat IMChat *chat = [BlueBubblesHelper getChat: data[@"chatGuid"] :transaction]; // get the message [BlueBubblesHelper getMessageItem:(chat) :(data[@"messageGuid"]) completionBlock:^(IMMessage *message) { - // find the message item corresponsing to the part index + // find the message item corresponding to the part index IMMessageItem *messageItem = (IMMessageItem *)message._imMessageItem; NSObject *items = messageItem._newChatItems; IMMessagePartChatItem *item; @@ -619,6 +628,7 @@ IMChat *chat = [BlueBubblesHelper getChat: data[@"chatGuid"] :transaction]; [chat retractMessagePart:(item)]; }]; ``` + {% endcode %} As with editing a message, the part index is crucial to know which part has been unsent and then use the `IMMessagePartChatItem` in the method correctly. @@ -626,4 +636,4 @@ As with editing a message, the part index is crucial to know which part has been ## Currently Known Issues 1. Sometimes, the `IMMessagePartChatItem` will not exist. This is almost always for messages that are old. If this happens, tapbacks won't work, and replies will have a weird bug where they attach to an "empty" message. See this [ticket](https://github.com/BlueBubblesApp/bluebubbles-helper/issues/11) for more details. -2. The reaction function currently doesn't support reacting to a message with multiple parts, for example a message with multiple attachments. This is likely also to do with `IMMessagePartChatItem` but we haven't figured it out quite yet. See this [ticket ](https://github.com/BlueBubblesApp/bluebubbles-helper/issues/8)for more details. +2. The reaction function currently doesn't support reacting to a message with multiple parts, for example a message with multiple attachments. This is likely also to do with `IMMessagePartChatItem` but we haven't figured it out quite yet. See this [ticket](https://github.com/BlueBubblesApp/bluebubbles-helper/issues/8) for more details. diff --git a/private-api/installation.md b/private-api/installation.md index 139cab0..a432d4b 100644 --- a/private-api/installation.md +++ b/private-api/installation.md @@ -9,7 +9,7 @@ In order to get Private API features, you must disable MacOS extra security meas {% endhint %} {% hint style="info" %} -Disabling SIP can be challenging, we recommend joining our [Discord ](https://discord.gg/BdsGwREh)to get assistance with the process if you need it! +Disabling SIP can be challenging, we recommend joining our [Discord](https://discord.gg/BdsGwREh) to get assistance with the process if you need it! {% endhint %} {% hint style="danger" %} @@ -64,17 +64,18 @@ Please follow the instructions for your macOS version in the tabs below. {% tabs %} {% tab title="macOS 10.13-10.15 (Sierra-Catalina)" %} + 1. Open Terminal on your macOS device -2. Run the following command to disable Library Validation and enter your password when prompted. +2. Run the following command to disable Library Validation and enter your password when prompted. `sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true` 3. Run the following commands to force your Mac to reboot into recovery mode: * **WARNING**: _DO NOT do this step or step 4-5_ if you are running dos1dude's patched High Sierra/Mojave/Catalina. It may temporarily brick your Mac until you reset your NVRAM/PRAM - * **If you are on **_**a real Mac with official macOS**_, do the following: + * **If you are on** _**a real Mac with official macOS**_, do the following: 1. **WARNING**: This will instantly reboot your Mac. Save everything before executing this command! 2. `sudo nvram recovery-boot-mode=unused` 3. `sudo reboot recovery` - * **If you are using **_**a Virtual Machine or a patched macOS software**_, follow [this guide.](https://docs.bluebubbles.app/server/advanced/running-on-macos-vm/disable-sip-on-vms) + * **If you are using** _**a Virtual Machine or a patched macOS software**_, follow [this guide.](https://docs.bluebubbles.app/server/advanced/running-on-macos-vm/disable-sip-on-vms) 4. When you are booted into `Recovery Mode`: * Click on `Utilities` in the top menu bar * Select `Terminal` @@ -86,11 +87,11 @@ Please follow the instructions for your macOS version in the tabs below. 8. Download the latest [BlueBubbles Helper Bundle](https://github.com/BlueBubblesApp/BlueBubbles-Server-Helper/releases) for MacForge/MySIMBL (please pay attention to macOS version on the .zip file) 9. If you have not already, unzip the ZIP file containing the `BlueBubblesHelper.bundle` 10. Follow the instructions below for either MacForge or mySIMBL - * **If you installed **_**MacForge**_ + * **If you installed** _**MacForge**_ 1. Open the `MacForge App`, then drag and drop the `.bundle` file into the `Manage Plug-ins` page/tab. 2. This will automatically install this helper plugin. To verify, you may check under the `/Library/Application Support/MacEnhance/Plugins/` directory, where you should see `BlueBubblesHelper.bundle` 3. Confirm that the BlueBubblesHelper plugin is toggled to `library`, and not `user`, within MacForge (the icon should show 2 people, not 1 person) - * **If you installed **_**mySIMBL**_ + * **If you installed** _**mySIMBL**_ 1. Open the `mySIMBL App`, then go to the `Manage` tab 2. Click the `+` button and select the `BlueBubblesHelper.bundle` 3. Verify that the bundle is enabled and running @@ -102,8 +103,9 @@ Please follow the instructions for your macOS version in the tabs below. {% endtab %} {% tab title="macOS 11+ (Big Sur+)" %} + 1. Open Terminal on your macOS device -2. Run the following command to disable Library Validation and enter your password when prompted. +2. Run the following command to disable Library Validation and enter your password when prompted. `sudo defaults write /Library/Preferences/com.apple.security.libraryvalidation.plist DisableLibraryValidation -bool true` 3. Follow the instructions below for your device type @@ -154,14 +156,14 @@ Here are some basic troubleshooting steps. Please try these out, and if you need * Try force quitting and reopening the server (with private API switch toggled on), and then force quit and reopen the iMessage app * Make sure your bundle is toggled to "library" mode in MacForge / mySIMBL (the icon next to it should have 2 people, not 1 person) * If you are on Apple Silicon, make sure you have Beta MacForge and that the BlueBubblesHelper bundle has a green dot for Apple Silicon. -* Check the MacForge / mySIMBL system tab. It should show these values on Intel: +* Check the MacForge / mySIMBL system tab. It should show these values on Intel: - ![](.gitbook/assets/image.png) + ![Selected](.gitbook/assets/image.png) or it should show all green dots on Apple Silicon. - * If you see Library Validation enabled, try step 2 of the [#instructions](installation.md#instructions "mention") again. - * If you see System Integrity Protection enabled, run `csrutil status` inside Terminal, then join our Discord and let us know what the output is. - * If any of the checkboxes are not checked, make sure you are running MacForge inside an Administrator account with all privileges. + * If you see Library Validation enabled, try step 2 of the [#instructions](installation.md#instructions "mention") again. + * If you see System Integrity Protection enabled, run `csrutil status` inside Terminal, then join our Discord and let us know what the output is. + * If any of the checkboxes are not checked, make sure you are running MacForge inside an Administrator account with all privileges. If none of this works, you should join our Discord and the developers will be able to help you out. In your post, please include your macOS version, Mac chipset (Intel / Apple Silicon), your bundle version, your server version, and a picture of the MacForge / mySIMBL system. Thanks! diff --git a/server/advanced/byo-proxy-service-guides/cloudflare-with-a-custom-domain.md b/server/advanced/byo-proxy-service-guides/cloudflare-with-a-custom-domain.md index 443be61..b669a8c 100644 --- a/server/advanced/byo-proxy-service-guides/cloudflare-with-a-custom-domain.md +++ b/server/advanced/byo-proxy-service-guides/cloudflare-with-a-custom-domain.md @@ -33,7 +33,7 @@ Cons: 5. in BlueBubbles settings set the proxy service to dynamic dns and enter your hostname and port 6. Try to connect the server using the Android, Desktop, or Web App to see if it works -### **Setting** C**loudflare to launch at boot** +### **Setting Cloudflare to launch at boot** 1. in the terminal type `sudo cloudflared service install` 2. download the `com.cloudflare.cloudflared.plist` template and replace \[YOUR TUNNEL ID] to your cloudflare tunnel id without the brackets (if your forgot it in the terminal type `cloudflared tunnel list` and it should show up) [https://raw.githubusercontent.com/Rihcus/Bluebububbles-Cloudflare-guide/main/com.cloudflare.cloudflared.plist](https://raw.githubusercontent.com/Rihcus/Bluebububbles-Cloudflare-guide/main/com.cloudflare.cloudflared.plist) diff --git a/server/advanced/byo-proxy-service-guides/nginx-manual-setup.md b/server/advanced/byo-proxy-service-guides/nginx-manual-setup.md index eb29d80..fd2a9d3 100644 --- a/server/advanced/byo-proxy-service-guides/nginx-manual-setup.md +++ b/server/advanced/byo-proxy-service-guides/nginx-manual-setup.md @@ -51,18 +51,18 @@ Of course, there are certain things that will vary depending on your configurati The following is the recommended configuration for BlueBubbles to work behind an Nginx proxy. For easiest configuration, this should be placed in a new file at `/etc/nginx/conf.d/bluebubbles.conf` -``` +```config server { - listen 80; - server_name ; + listen 80; + server_name ; proxy_set_header Host $host; proxy_http_version 1.1; - proxy_set_header Connection "Upgrade"; - proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "Upgrade"; + proxy_set_header Upgrade $http_upgrade; client_max_body_size 512M; location / { - proxy_pass http://:; + proxy_pass http://:; } } ``` @@ -90,7 +90,7 @@ Before writing your config, these apache modules are required for the config to The following is the recommended configuration for BlueBubbles to work behind an Apache proxy. This should be placed in a new file at `/etc/httpd/conf.d/bluebubbles.conf` -``` +```config ServerName @@ -122,10 +122,10 @@ On certain Linux distributions, the configuration directory may be at `/etc/apac For reference, the following is the minimum viable configuration for BlueBubbles to work behind an Apache proxy. This configuration does not need the `mod_headers` module. -``` +```config ServerName {server name} - + ProxyPass http://:/ ProxyPass ws://:/ @@ -137,14 +137,14 @@ For reference, the following is the minimum viable configuration for BlueBubbles The following is the recommended configuration template for HAProxy. This should be in `/etc/haproxy/haproxy.cfg`. -``` +``` config frontend - use_backend [if {ACL}] + use_backend [if {ACL}] backend - timeout client 60m - timeout http-keep-alive 5m - server : + timeout client 60m + timeout http-keep-alive 5m + server : ``` Keep in mind that HAProxy ACL configurations can be complex. For more information on configuring HAProxy ACLs, see [this HAProxy blog post](https://www.haproxy.com/blog/introduction-to-haproxy-acls/). @@ -180,7 +180,7 @@ For simplicity's sake, we will only be covering SSL offloading configuration in #### Certbot, the easy solution -The simplest solution for SSL certificate management and configuration is [Certbot](https://certbot.eff.org/). Cerbot is a tool built by the Electronic Frontier Foundation (EFF) and leverages [Let's Encrypt](https://letsencrypt.org/) to issue free certificates and then automatically install them in your existing server/proxy configuration. Certbot supports automatic SSL configuration for Apache, Nginx, HAProxy, and Plesk. +The simplest solution for SSL certificate management and configuration is [Certbot](https://certbot.eff.org/). Certbot is a tool built by the Electronic Frontier Foundation (EFF) and leverages [Let's Encrypt](https://letsencrypt.org/) to issue free certificates and then automatically install them in your existing server/proxy configuration. Certbot supports automatic SSL configuration for Apache, Nginx, HAProxy, and Plesk. If you are using HAProxy, there are some added layers of complexity, but Certbot can still be used to seamlessly automate the management and renewal of SSL certificates. Skip to the section _Certbot on HAProxy_. @@ -214,7 +214,7 @@ Per Certbot's website: "Certificate installation with HAProxy is complicated." T * HAProxy is not a web server, so it can not be used in `standalone` mode to run an HTTP server and respond to Let's Encrypt's HTTP-01 challenges * HAProxy requires a single .pem file that includes both the public certificate and the private key. This is not automatically generated by Certbot. -However, there are several guides available online which show you how to generate a certificate, install it, and then automate the renewall process. In short, it works by diverting HTTP calls to the `.well-known` directory (where HTTP-01 challenges are stored) to the localhost where Certbot is running its own web server during the challenge. Then, the new certificate and key are combined into a .pem file with a simple bash script. +However, there are several guides available online which show you how to generate a certificate, install it, and then automate the renewal process. In short, it works by diverting HTTP calls to the `.well-known` directory (where HTTP-01 challenges are stored) to the localhost where Certbot is running its own web server during the challenge. Then, the new certificate and key are combined into a .pem file with a simple bash script. * [Servers for Hackers - LetsEncrypt with HAProxy](https://serversforhackers.com/c/letsencrypt-with-haproxy) (Recommended) * [Skarlso - How to HTTPS with Hugo LetsEncrypt and HAProxy](https://skarlso.github.io/2017/02/15/how-to-https-with-hugo-letsencrypt-haproxy/) @@ -234,7 +234,7 @@ These example configuration files are the auto-generated files by Certbot and ar Contents of `/etc/nginx/conf.d/bluebubbles.conf` (could also be `/etc/nginx/vhosts.d/bluebubbles.conf`, depending on distro) -``` +```config server { listen 443 ssl; server_name ; @@ -246,7 +246,7 @@ Contents of `/etc/nginx/conf.d/bluebubbles.conf` (could also be `/etc/nginx/vhos location / { proxy_pass http://:; } - + ssl_certificate /etc/letsencrypt/live//fullchain.pem ssl_certificate_key /etc/letsencrypt/live//privkey.pem include /etc/letsencrypt/options-ssl-nginx.conf @@ -283,7 +283,7 @@ ssl_prefer_server_ciphers off; Contents of `/etc/httpd/conf.d/bluebubbles.conf` (could also be `/etc/apache2/vhosts.d/bluebubbles.conf`, depending on Linux distribution) -``` +``` config ServerName @@ -325,7 +325,7 @@ For HAProxy, you need to have a .pem file that includes both the public certific Contents of `/etc/haproxy/haproxy.cfg` -``` +```config frontend bind *:80 bind *:443 ssl crt /etc/ssl/certs/mysite.pem diff --git a/server/advanced/byo-proxy-service-guides/nginx-proxy-manager.md b/server/advanced/byo-proxy-service-guides/nginx-proxy-manager.md index 297f066..a92313d 100644 --- a/server/advanced/byo-proxy-service-guides/nginx-proxy-manager.md +++ b/server/advanced/byo-proxy-service-guides/nginx-proxy-manager.md @@ -27,11 +27,11 @@ description: >- 8. Check all 4 options 3. Your Bluebubbles instance should now be accessible at `https://bb.yourdomain.com` ! -![](<../../.gitbook/assets/image (6).png>) +![SSL Settings](<../../.gitbook/assets/image (6).png>) -![](<../../.gitbook/assets/image (3).png>) +![Connection Settings](<../../.gitbook/assets/image (3).png>) -![](../../.gitbook/assets/image.png) +![Proxy Host](../../.gitbook/assets/image.png) #### Credit diff --git a/server/advanced/disabling-sip-on-unofficial-macs-for-the-private-api.md b/server/advanced/disabling-sip-on-unofficial-macs-for-the-private-api.md index c52c168..561208e 100644 --- a/server/advanced/disabling-sip-on-unofficial-macs-for-the-private-api.md +++ b/server/advanced/disabling-sip-on-unofficial-macs-for-the-private-api.md @@ -8,7 +8,7 @@ Here are some steps that have worked for our users running various different uno Use the OpenCore Configurator and check the following boxes: -![](<../.gitbook/assets/image (1).png>) +![SIP Config](<../.gitbook/assets/image (1).png>) Once complete, build OpenCore again and reboot. Done! @@ -24,60 +24,51 @@ Once complete, build OpenCore again and reboot. Done! ### Method 1 -1. Start by booting to macOS and opening a Terminal application window. Next, enter the command given below. This will create a NVRAM variable with the desired value, but misspelled variable name. This misspelling will be corrected in a later step.\ +1. Start by booting to macOS and opening a Terminal application window. Next, enter the command given below. This will create a NVRAM variable with the desired value, but misspelled variable name. This misspelling will be corrected in a later step.\ - - ``` + ```bash sudo nvram Asr-active-config=%7f%00%00%00 ``` +2. Shutdown macOS. Add the following to the bottom of the VMX file:\ -2. Shutdown macOS. Add the following to the bottom of the VMX file:\ - - - ``` + ```config bios.forceSetupOnce = "TRUE" ``` \ Save the VMX file and boot up macOS.\ -3. You should be brought to the Boot Manager screen below. Select the `EFI Internal Shell`, as shown below.\ - +3. You should be brought to the Boot Manager screen below. Select the `EFI Internal Shell`, as shown below.\ - [![](https://i.stack.imgur.com/muLxs.png)](https://i.stack.imgur.com/muLxs.png) + [![Boot Manager](https://i.stack.imgur.com/muLxs.png)](https://i.stack.imgur.com/muLxs.png) +4. Set the current filesystem to the EFI volume. This should be the mapped `fs0` filesystem, so you would enter the following\ -4. Set the current filesystem to the EFI volume. This should be the mapped `fs0` filesystem, so you would enter the following\ - - - ``` + ```bash fs0: ``` \ Next, verify the label is `EFI` by entering the command below.\ - - ``` + ```bash vol ``` \ If wrong, then try `fs1:`, `fs2:`, `fs3:`, ....\ -5. Enter the command below to save the `Asr-active-config` variable to the file `csr.bin`.\ - +5. Enter the command below to save the `Asr-active-config` variable to the file `csr.bin`.\ - ``` + ```bash dmpstore Asr-active-config -s csr.bin ``` \ Next, enter the command below to edit the `csr.bin` file.\ - - ``` + ```bash hexedit csr.bin ``` @@ -90,31 +81,26 @@ Once complete, build OpenCore again and reboot. Done! \ Enter the command below to create the `csr-active-config` variable in NVRAM.\ - - ``` + ```bash dmpstore -l csr.bin ``` \ SIP will now be disabled on the next boot of macOS. If desired, enter the command below to remove the `Asr-active-config` variable from NVRAM.\ - - ``` + ```bash dmpstore -d Asr-active-config ``` +6. Enter the command below to leave the command shell.\ -6. Enter the command below to leave the command shell.\ - - - ``` + ```bash exit ``` \ From the `Boot Manager`, select `Mac OS X` to boot macOS.\ - ### Method 2 (Requires VMWare Workstation Pro) 1. Shutdown your VM diff --git a/server/advanced/macos-virtualization/running-a-macos-vm/deploying-macos-in-vmware-on-windows-full-guide.md b/server/advanced/macos-virtualization/running-a-macos-vm/deploying-macos-in-vmware-on-windows-full-guide.md index 185aa28..813b9ed 100644 --- a/server/advanced/macos-virtualization/running-a-macos-vm/deploying-macos-in-vmware-on-windows-full-guide.md +++ b/server/advanced/macos-virtualization/running-a-macos-vm/deploying-macos-in-vmware-on-windows-full-guide.md @@ -33,7 +33,7 @@ The first step in setting up a virtual machine is getting an image that is compa 2. Extract the OpenCore ZIP file, and open the extracted folder. 3. Navigate into `Utilities\macrecovery`. 4. Holding `Shift` on your keyboard, right-click your explorer window and select `Open PowerShell window here`. -5. Run the python command corresponding to the macOS version you want to download, found in the OpenCore Install Guide. +5. Run the python command corresponding to the macOS version you want to download, found in the OpenCore Install Guide. * [https://dortania.github.io/OpenCore-Install-Guide/installer-guide/winblows-install.html#downloading-macos](https://dortania.github.io/OpenCore-Install-Guide/installer-guide/winblows-install.html#downloading-macos) * Running the command will download the `BaseSystem.dmg` image from Apple's servers @@ -45,9 +45,10 @@ The first step in setting up a virtual machine is getting an image that is compa **This is not recommended for inexperienced users!** - ``` + ```bash python ./macrecovery.py -b Mac-27AD2F918AE68F61 -m 00000000000000000 download ``` + {% endhint %} 6. Next, cut/copy the `BaseSystem.dmg` file (generated in the `macrecovery` folder), to your user profile's `Documents` folder @@ -158,13 +159,13 @@ This section will detail how to patch your virtual machine in order to properly 3. Open your virtual machine's original `Configuration File` (`.vmx`) in a text editor (i.e. Notepad) 4. Paste the following line into the `.vmx` file and save it. -``` +```vmx smc.version = "0" ``` * If you have an AMD CPU, also add the following to your `.vmx` file. -``` +```vmx cpuid.0.eax = "0000:0000:0000:0000:0000:0000:0000:1011" cpuid.0.ebx = "0111:0101:0110:1110:0110:0101:0100:0111" cpuid.0.ecx = "0110:1100:0110:0101:0111:0100:0110:1110" @@ -180,9 +181,10 @@ cpuid.1.edx = "0000:0111:1000:1011:1111:1011:1111:1111" If your VM is macOS Ventura, you may need to add **(or edit)** the following to enable internet connectivity: -``` +```vmx ethernet0.virtualDev = "vmxnet3" ``` + {% endhint %} #### Booting the Virtual Machine @@ -230,16 +232,16 @@ By default, your macOS deployment will _not_ support iServices such as iMessage. 1. Boot up your macOS virtual machine and login. 2. Open Safari and download `Clover Configurator`. - * Website: https://mackie100projects.altervista.org/download-clover-configurator/ + * Website: 3. Open `Clover Configurator`. * You may need to allow it to run via `System Preferences -> Security & Privacy`. 4. Once opened, navigate to the `SMBIOS` tab in the sidebar. -5. Find the up/down arrow button under the large "question mark" image, and to the right of the `Update Firmward Only` checkbox. +5. Find the up/down arrow button under the large "question mark" image, and to the right of the `Update Firmware Only` checkbox. 6. Click on the up/down arrow button and select any product made in 2019 or newer. * We recommend `MacPro7,1` or `MacBookPro16,1` 7. Copy the following configuration to an editor (i.e. Notepad), on your host computer (Windows). -``` +``` config board-id = "AAA" hw.model.reflectHost = "FALSE" hw.model = "BBB" @@ -269,7 +271,7 @@ efi.nvram.var.MLB = "EEE" 9. Find the `board-id.reflectHost` configuration and verify that it is set to `"TRUE"`. 10. Find the `ethernet0.addressType` configuration and change it from `"generated"` to `"static"` 11. In your browser, go to the following link to grab an "OUI" for the configuration: - * https://hwaddress.com/company/apple-inc/ + * * The OUI contains 3 segments, each containing 2 characters. * It does not matter which OUI you choose. Choose any. 12. Find the `ethernet0.generatedAddress` configuration and change the first 3 segments to match the 3 segments of your chosen OUI. @@ -289,5 +291,5 @@ Here are a few final checks to make sure that your macOS virtual machine is setu * When the macOS virtual machine is booted & running, click on the `Apple Logo` and select `About this Mac`. Verify that the serial number listed matches the serial number you configured in the steps above. * Open `System Preferences` and open your `Date & Time` settings. Verify that your timezone is set correctly and your time is properly synced. - * If you are unsure, you can open Safari and go to https://time.is to see if your time synchronization is misaligned. + * If you are unsure, you can open Safari and go to to see if your time synchronization is misaligned. * If your time synchronization is misaligned, you can synchronize it by opening `Terminal` and running this command: `sudo ntpdate -vu time.apple.com` diff --git a/server/advanced/macos-virtualization/running-a-macos-vm/enabling-imessage-in-a-vm.md b/server/advanced/macos-virtualization/running-a-macos-vm/enabling-imessage-in-a-vm.md index f388fad..6392bac 100644 --- a/server/advanced/macos-virtualization/running-a-macos-vm/enabling-imessage-in-a-vm.md +++ b/server/advanced/macos-virtualization/running-a-macos-vm/enabling-imessage-in-a-vm.md @@ -8,7 +8,7 @@ iServices are 99% likely to not run on your unofficial Mac until you successfull ## OpenCore -If you made your macOS install using OpenCore, follow their [guide ](https://dortania.github.io/OpenCore-Post-Install/universal/iservices.html)to enable iServices. +If you made your macOS install using OpenCore, follow their [guide](https://dortania.github.io/OpenCore-Post-Install/universal/iservices.html) to enable iServices. ## VMWare @@ -37,12 +37,11 @@ If you would like to use a _lower_ macOS version than Catalina, you will need to * We recommend to use a browser with TOR functionality for this step, such as Brave Browser (use "New private window with Tor" option). This is so Apple does not rate limit you when checking serials (TOR randomizes your IP address and location every time you load the page, at the cost of network speed). * **Choose a Mac Address** * **Derive the corresponding ROM Value** -2. Open up a Notepad window, and type the following information (you will need this later):\ +2. Open up a Notepad window, and type the following information (you will need this later):\ \ (AMD USERS PLEASE MAKE SURE TO READ THE ORANGE NOTE ABOVE)\ - - ``` + ```config board-id = "Mac-27AD2F918AE68F61" hw.model.reflectHost = "FALSE" hw.model = "MacPro7,1" @@ -54,13 +53,14 @@ If you would like to use a _lower_ macOS version than Catalina, you will need to efi.nvram.var.ROM = "" efi.nvram.var.MLB = "" ``` + 3. Fully close your VM and VMware. Nothing VMware related (besides this guide of course) should be running. 4. Open File Explorer, click Documents, open the folder named Virtual Machines, open the folder with the name of your VM, and find your .vmx file (VMware virtual machine configuration). Open it with Notepad. 5. Scroll to the line `board-id.reflectHost = "FALSE"` and replace `FALSE` with `TRUE`. 6. Find the line `firmware = "efi"` and paste everything from the other Notepad window right below this. 7. Find the line `ethernet0.addressType = "generated"` and replace `generated` with `static`. 8. Find the line `ethernet0.generatedAddress = "xx:xx:xx:xx:xx:xx"` and replace the entire line with `ethernet0.Address = ""` -9. Find the line `ethernet0.generatedAddressOffset = "0"` and replace the entire line with `ethernet0.checkMACAddress = "false"`.\ +9. Find the line `ethernet0.generatedAddressOffset = "0"` and replace the entire line with `ethernet0.checkMACAddress = "false"`.\ {% hint style="warning" %} @@ -68,13 +68,13 @@ If you would like to use a _lower_ macOS version than Catalina, you will need to Make sure that your VMX does not have any duplicate items from your previous modifications to make the VM start up! You may need to delete the following from the previous modifications: - ``` + ```config smbios.reflectHost = "TRUE" hw.model = "" board-id = "" ``` - {% endhint %} + {% endhint %} 10. Save the .vmx file inside Notepad, boot it up, and try signing into your Apple ID from within the iMessage app. If all went well, you will be able to sign in and send messages. @@ -92,7 +92,7 @@ If you would like to use a _lower_ macOS version than Catalina, you will need to Run the following in terminal: -``` +```bash sudo rm -rf ~/Library/Caches/com.apple.iCloudHelper* sudo rm -rf ~/Library/Caches/com.apple.Messages* sudo rm -rf ~/Library/Caches/com.apple.imfoundation.IMRemoteURLConnectionAgent* diff --git a/server/advanced/macos-virtualization/running-macos-in-docker.md b/server/advanced/macos-virtualization/running-macos-in-docker.md index aec633a..59a76ad 100644 --- a/server/advanced/macos-virtualization/running-macos-in-docker.md +++ b/server/advanced/macos-virtualization/running-macos-in-docker.md @@ -20,16 +20,16 @@ Actually this (`Docker-OSX`) is a QEMU VM running under an Arch Docker. However `TigerVNC-Viewer` or equivalent VNC Viewer/Client (Optional) `screen` for interacting with docker `-ai` -## Initiate base image: +## Initiate base image -``` +```bash #!/bin/bash docker run -it \ --name macos_base \ --device /dev/kvm \ -p 50922:10022 \ -p 5999:5999 \ - -e NOPICKER=true \ + -e NOPICKER=true \ -v /tmp/.X11-unix:/tmp/.X11-unix \ -e "DISPLAY=${DISPLAY:-:0.0}" \ -e EXTRA="-display none -vnc 0.0.0.0:99" \ @@ -49,14 +49,14 @@ docker run -it \ Explain: find `mac_hdd_ng.img` from `/var/lib/docker` (make sure file size make sense), copy to current folder -``` +```bash #!/bin/bash sudo cp `sudo find /var/lib/docker -size +10G -name mac_hdd_ng.img | head -1` . ``` ## Generate unique serial -``` +```bash #!/bin/bash mkdir tmp && cd tmp curl https://raw.githubusercontent.com/sickcodes/Docker-OSX/master/custom/generate-unique-machine-values.sh -O @@ -72,7 +72,7 @@ OR if you already have a working serial configs and just want to migrate to dock * Create file with `nano my_permanent_serial_number.sh` * Content of the file -``` +```sh export DEVICE_MODEL="DEVICE_MODEL_HERE" export SERIAL="SERIAL_HERE" export BOARD_SERIAL="BOARD_SERIAL_HERE" @@ -86,7 +86,7 @@ export HEIGHT="768" ## First run -``` +```bash #!/bin/bash source ./my_permanent_serial_number.sh sudo docker run -i \ @@ -120,7 +120,7 @@ sudo docker run -i \ `screen` is totally optional, I just want to have stdio attached for debugging in QEMU shell -``` +```bash #!/bin/bash screen -dmS macos-docker docker start -ai macos ``` diff --git a/server/basic-guides/port-forwarding-and-dynamic-dns.md b/server/basic-guides/port-forwarding-and-dynamic-dns.md index f765197..6b8ebdd 100644 --- a/server/basic-guides/port-forwarding-and-dynamic-dns.md +++ b/server/basic-guides/port-forwarding-and-dynamic-dns.md @@ -7,7 +7,7 @@ description: >- # Port Forwarding & Dynamic DNS -Before you begin, make sure that the following pre-requisites apply to you. If _**any** _ of them do not apply to you, this will not be possible for you, and you may need to stick to the build-in proxy services, pay for one, or self-host a reverse proxy. +Before you begin, make sure that the following pre-requisites apply to you. If _**any**_ of them do not apply to you, this will not be possible for you, and you may need to stick to the build-in proxy services, pay for one, or self-host a reverse proxy. ## Pre-requisites