diff --git a/content/getting-started/configuration/_index.en.md b/content/getting-started/configuration/_index.en.md index 7c40fba..2d5fd10 100644 --- a/content/getting-started/configuration/_index.en.md +++ b/content/getting-started/configuration/_index.en.md @@ -5,15 +5,15 @@ weight = 20 +++ ## Setting up pwnagotchi config -If you have followed the guide, your SD card should still be mounted to your PC. There should be two partitions, one called "boot" and one called "rootfs". On Windows, you will see just the boot partition, which is okay for now. +If you have followed the guide, your SD card should still be mounted to your PC. There should be two partitions: one called "boot" and one called "rootfs". (On Windows, you will see just the boot partition, which is okay for now.) ![Two different partitions in Thunar file manager](https://github.com/pwndevelopers/community-wiki/assets/21370314/cfa1dcba-45ed-4a87-8a02-50fda15a0e9e) -## At this point you have 2 options. -Insert the SD card and boot up the pwnagotchi and edit your config.toml later or, the other option, add one to the boot partition +## At this point you have 2 options: +**A.** Insert the SD card, boot up the Pwnagotchi and edit your `config.toml` later. -Mount the boot partition, and open it. In there, you will create a file named `config.toml`. Open this file in your favourite text editor, and pay close attention to next steps. +**B.** Add `config.toml` to the boot partition: Mount the boot partition and open it. In there, create a file named `config.toml`. Open this file in your favorite text editor, then pay close attention to the configuration recommendations described below. @@ -32,37 +32,35 @@ ui.display.type = "waveshare_3" #Change this to match your screen ui.display.color = "black" ui.fps = 1 ``` -#### Explanation of stuff you probably want to change +#### Explanation of stuff you probably want to change in `config.toml`: -`main.name` specifies the name of your pwny. You can enter whatever you like in there. +`main.name` → Specifies the name of your Pwny. You can choose whatever name you desire here. -`main.lang` specifies the language of your pwny. For language reference, see [here](https://pwnagotchi.ai/configuration/#choose-your-unit-s-language). +`main.lang` → Specifies the language of your Pwny's UI. A list of available languages is [here](https://pwnagotchi.ai/configuration/#choose-your-unit-s-language). -`main.whitelist` is a list of access points that **WON'T** be pwned, so for example your home WiFi. You can enter it's SSID (The Name of the Wi-Fi router) or it's MAC address there. +`main.whitelist` → A list of access points that **WON'T** be pwned. You can enter either an SSID (= the name of the Wi-Fi router) or a MAC address here. (It is a good idea to add your home Wi-Fi network here.) -`main.plugins.grid` controls the bevaiour of the Grid, which is sort of a backend for the pwny, that has statistics, you can message others using it, etc. Read more about Grid [here](https://pwnagotchi.ai/configuration/#set-your-pwngrid-preferences). +`main.plugins.grid` → Controls the behavior of the Grid, which is sort of a backend for the Pwny. The server maintains statistics about individual units and also allows you to message others using your Pwny. (Learn more about the Grid [here](https://pwnagotchi.ai/configuration/#set-your-pwngrid-preferences).) -`main.plugins.bt-tether.enabled = true` is necessary to get Bluetooth conenction enabled. +`main.plugins.bt-tether.enabled = true` → This enables the Bluetooth connection, allowing you to see Pwny's UI on your phone. -`main.plugins.bt-tether.devices.XXX` here you configure your Bluetooth. You want to delete whichever section you do not use (i.e. if you have Android phone, delete every line with "ios" in it). +`main.plugins.bt-tether.devices.XXX` → These parameters are where you configure the Bluetooth connection. Be sure to delete whichever sections you will not use (_i.e.,_ if you have Android phone, delete every line with "ios" in it). Configuring this can get a little tricky, so here's a rundown of what to change: -Configuring this can get a little tricky, so here's a rundown of what to change. +`main.plugins.bt-tether.devices.ios-phone.ip` → The IP address at which your Pwny will be located at. (For simplicity you can leave this as the default, but you can change it.) -`main.plugins.bt-tether.devices.ios-phone.ip` is the IP address at which your pwny will be located at. For simplicity, leave this to default, but you can change it. +`main.plugins.bt-tether.devices.ios-phone.mac` → You should enter your phone's Bluetooth MAC address here. (Not sure how to determine this? Guides are available for [Android](https://www.esper.io/blog/kiosk-signage-android-mac-address-serial-tracking) and [iOS](https://www.wikihow.com/Check-Your-iPhone%27s-Bluetooth-Address).) -`main.plugins.bt-tether.devices.ios-phone.mac` in this field, you will enter your phone's BT MAC address. Guides on how to find those are here for [Android](https://www.esper.io/blog/kiosk-signage-android-mac-address-serial-tracking) and for [iOS](https://www.wikihow.com/Check-Your-iPhone%27s-Bluetooth-Address). +`main.plugins.bt-tether.devices.ios-phone.share_internet = true` → Change this to true if it isn't already. This is needed to share the internet connection of your phone with your Pwny (for uploading statistics, some plugins, time sync, etc). -`main.plugins.bt-tether.devices.ios-phone.share_internet = true` change this to true if it isn't, this is needed to share the internet connection of your phone with your pwny (for uploading stats, some plugins, time sync etc.) +`main.plugins.memtemp.enabled = true` → Enables a plugin that shows your Pwny system's load and temp. (This is nice to know.) You can change units and orientation, but what's above works best with phones. -`main.plugins.memtemp.enabled = true` enables plugin, that shows you your system's load and temp. Those are nice to know. You can change units and orientation, but what's above works best with phones. +`main.plugins.logtail.enabled = true` → Enables a plugin that lets you view Pwny's log in your phone. Nice for debugging if anything goes ass up — you can disable it when you are done with your Pwny. -`main.plugins.logtail.enabled = true` enabled plugin that lets you view pwny's log in your phone. Nice for debugging if anything goes ass up, you can disable it when you are done with your pwny. +`ui.web.enabled = true` → Enables the webUI. Keep this enabled, otherwise you won't be able to see your Pwny on your phone. Be sure to change the default credentials for accessing this (see `ui.web.username` and `ui.web.password`). -`ui.web.enabled = true` enables the webUI, keep this enabled, otherwise you won't be able to see your pwny in your phone. However you will have to change some things, see below. +`ui.web.username = "changeme"` and `ui.web.password = "changeme"` → As the default credentials suggest, it is highly recommended to change your login username and password to something only you know. -`ui.web.username = "changeme"` and `ui.web.password = "changeme"` as the text says, it is highly recommended to change your login username and password, again, from security standpoint. - -`ui.display.enabled = false` this disables the physical display, since we don't have a display attached to our pwnagotchi, we can disable it. +`ui.display.enabled = false` → This disables the physical display. This should remain disabled unless you've attached a screen to your Pwny. (If you're using an attached screen on your Pwny, set this to `true`.) --- diff --git a/content/getting-started/encryption/_index.en.md b/content/getting-started/encryption/_index.en.md index 4982c8f..8fa8ce1 100644 --- a/content/getting-started/encryption/_index.en.md +++ b/content/getting-started/encryption/_index.en.md @@ -6,13 +6,13 @@ weight = 60 **TL;DR:** Click [here](#a-step-by-step-guide) to jump directly to the step-by-step encryption guide. -What if you loose your pwnagotchi? All your data (api keys, handshakes, etc) will be lost. Also, the person who finds your little friend will be able to read your data. +What if you lose your Pwnagotchi? All your data (API keys, handshakes, etc) will be lost. Also, the person who finds your little friend will be able to read your data. -Although we cannot help you in not losing your device, we can help you prevent the leak of your data by using encryption. We will use [dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) subsystem of linux. +Although we cannot help you in not losing your device, we can help you prevent the leak of your data by using encryption. We will use [dm-crypt](https://en.wikipedia.org/wiki/Dm-crypt) subsystem of Linux. ### How it works -When pwnagotchi boots up, it will look for the file `/root/.pwnagotchi-crypted`. Every line in this file represents a luks-container that will be decrypted and mounted before pwnagotchi starts. +When Pwnagotchi boots up, it will look for the file `/root/.pwnagotchi-crypted`. Every line in this file represents a LUKS container that will be decrypted and mounted before Pwnagotchi starts. Each line follows this format: @@ -22,34 +22,34 @@ $container_name $container_path $mountpoint Where: -- `$container_name` is the name of the container, tipically `crypto -- `$container_path` is the path to the container file, tipically placed in the root (e.g. `/cryptoconfig`) +- `$container_name` is the name of the container, typically `crypto` +- `$container_path` is the path to the container file, typically placed in the root (e.g. `/cryptoconfig`) - `$mountpoint` is the path where the container will be mounted once it is decrypted (e.g. `/etc/pwnagotchi`) **Cool, but how is the decryption password provided?** -Once booted up, pwnagotchi will start a new hotspot with the following SSID/password: +Once booted up, Pwnagotchi will start a new hotspot with the following SSID/password: - **SSID:** `DECRYPT-ME` - **Password:** `pwnagotchi` After connected to this hotspot, you'll be redirected to a web page on your browser. -If you aren't redirected, configure the ip address of your device manually (ip: `192.168.0.3` - subnet mask: `255.255.255.0`) and open [http://192.168.0.10/](http://192.168.0.10/) in your browser. The web page will look like this: +If you aren't redirected, configure the IP address of your device manually (IP: `192.168.0.3` - subnet mask: `255.255.255.0`) and open [http://192.168.0.10/](http://192.168.0.10/) in your browser. The web page will look like this: ![Decryption web page](https://i.imgur.com/BRGATme.png) -Inside the webpage, you'll find as many input textbox as many luks container you have added inside the `/root/.pwnagotchi-crypted` file. For every container, provide the correct password. Once you have typed all the passwords, click `Submit`. +Inside the webpage, you'll see an input box for every LUKS container you have added inside the `/root/.pwnagotchi-crypted` file. For every container, provide the correct password. After typing all the passwords, click `Submit`. -Your pwnagotchi will decrypt every container with the provided password and complete the boot process starting the service. +Your Pwnagotchi will decrypt every container with the provided password and complete the boot process, starting the service. ### What files should you encrypt? The files to be encrypted depend solely on you and your level of paranoia. Generally, you should encrypt all files that may contain sensitive information. -What we suggest you do is to think about which files/folders you wouldn't want a stranger to see in the unfortunate event that you lose your pwnagotchi. At the same time, though, don't encrypt the entire contents of the disk, otherwise your pwnagotchi will no longer boot up. +What we suggest you do is to think about which files/folders you wouldn't want a stranger to see in the unfortunate event that you lose your Pwnagotchi. At the same time, though — don't encrypt the entire contents of the disk, otherwise your Pwnagotchi will no longer boot up. -A list of common directories that contains sensitive data and should be encrypted are: +A list of common directories that contain sensitive data and should be encrypted are: - Config directory: `/etc/pwnagotchi` - Handshakes directory: `/root/handshakes` @@ -57,7 +57,7 @@ A list of common directories that contains sensitive data and should be encrypte ### Fix decryption server bug in evilsocket image -In the evilsocket original image there is a bug with the decryption service (see this [issue](https://github.com/evilsocket/pwnagotchi/issues/879)). To fix it run the following command: +In evilsocket's original image, there is a bug with the decryption service (see this [issue](https://github.com/evilsocket/pwnagotchi/issues/879)). To fix it, run the following command: ```sh sudo chmod u+x /usr/bin/decryption-webserver @@ -67,29 +67,29 @@ sudo chmod u+x /usr/bin/decryption-webserver So you have read all the docs above, now it's time to encrypt some bits. Isn't it? -The following steps will guide you through the encryption of the **pwnagotchi's config directory** (i.e. `/etc/pwnagotchi`). +The following steps will guide you through the encryption of the **Pwnagotchi's config directory** (i.e. `/etc/pwnagotchi`) using commands run in your Linux terminal. -You can apply the same steps to basically every directory you want to encrypt and keep secure. Just replace `/etc/pwnagotchi` with the path to your directory (**always use absolute path**) and `cryptoconfig` with the name that you want to use for your container (tip: use `crypto` as the naming scheme). +You can apply the same steps to basically every directory you want to encrypt and keep secure. Just replace `/etc/pwnagotchi` with the path to your directory (**always use absolute path**) and `cryptoconfig` with the name that you want to use for your container (TIP: use `crypto` as the naming scheme). -**IMPORTANT: most of the operations requires root privileges. So run the commands either with `sudo` or use `sudo su` to become `root`.** +**IMPORTANT: Most of the operations requires root privileges. So run the commands either with `sudo` or use `sudo su` to become `root`.** #### 0. Backup your data -Before your start doing anything it's important that you **backup** your data in case something goes wrong and you have to restore the data. +Before you start doing anything, it's important that you **backup** your data in case something goes wrong and you have to restore the data. -Run the following command to backup and archive the directory content inside `/root/`: +Backup and archive the directory content inside `/root/`: ```sh tar -czvf /root/pwnagotchi_config.tar.gz /etc/pwnagotchi/ ``` -If you want to restore the data use the following command: +If you want to restore the data, use the following command to extract the contents of the archive in the current path: ```sh tar -xzvf pwnagotchi_config.tar.gz ``` -This will extract the content of the archive in the current path. Then move all the files back in their original place: +Then move all the files back in their original place: ```sh mv ./etc/pwnagotchi/* /etc/pwnagotchi @@ -97,17 +97,17 @@ mv ./etc/pwnagotchi/* /etc/pwnagotchi #### 1. Create the container file -Run the following command to create the container file: +Create the container file: ```sh dd if=/dev/zero of=/cryptoconfig bs=1M count=100 ``` -This will create a new file `/cryptoconfig` where all encrypted files will be stored. The size of the file will be of 100MB. Increase `count=100` in case you want to encrypt directories that are bigger. +This will create a new file (`/cryptoconfig`) where all encrypted files will be stored. The size of the file will be 100MB. Increase `count=100` if you want to encrypt directories that are bigger. -#### 2. Make the container luks-ready +#### 2. Make the container LUKS-ready -Run the following command to setup luks inside the container: +Set up LUKS inside the container: ```sh cryptsetup luksFormat /cryptoconfig @@ -115,21 +115,21 @@ cryptsetup luksFormat /cryptoconfig Type `YES` when it asks you if you are sure to overwrite data. -After that, you'll be asked for a password. This password will be used to decrypt the container so set a strong password and remember it, otherwise you'll not be able to decrypt your files. +After that, you'll be asked for a password. This password will be used to decrypt the container, so set a strong password and remember it (otherwise you'll not be able to decrypt your files). #### 3. Open the container -Open the newly created container by running this command: +Open the newly created container: ```sh cryptsetup luksOpen /cryptoconfig cryptoconfig ``` -You'll be asked for the password, type the password that you set in step 2. +You'll be asked for the password. Type the password that you set in step #2. #### 4. Create ext4 filesystem -To create a `ext4` filesystem inside the container, run: +To create a `ext4` filesystem inside the container: ```sh mkfs.ext4 /dev/mapper/cryptoconfig @@ -137,7 +137,7 @@ mkfs.ext4 /dev/mapper/cryptoconfig #### 5. Mount the filesystem -Mount the filesystem by running: +Mount the filesystem: ```sh mount /dev/mapper/cryptoconfig /mnt @@ -153,7 +153,7 @@ cp /etc/pwnagotchi/* /mnt #### 7. Remove old files -Remove the existing unencrypted files from the original location by running: +Remove the existing unencrypted files from the original location: ```sh rm /etc/pwnagotchi/* @@ -161,15 +161,15 @@ rm /etc/pwnagotchi/* #### 8. Unmount the container -Unmount the container running: +Unmount the container: ```sh umount /mnt ``` -#### 9. Configure pwnagotchi to decrypt the new container +#### 9. Configure Pwnagotchi to decrypt the new container -Last step is to tell pwnagotchi about the newly created container. To do this, run: +The last step is to tell Pwnagotchi about the newly created container. To do this, run: ```sh echo "cryptoconfig /cryptoconfig /etc/pwnagotchi" >> /root/.pwnagotchi-crypted @@ -177,15 +177,15 @@ echo "cryptoconfig /cryptoconfig /etc/pwnagotchi" >> /root/.pwnagotchi-crypted #### 10. Reboot -Done! You have succesfully setup encryption on your pwnagotchi. If you want to create other containers repeat the same process and change the directory path and container name. +Done! You have successfully set up encryption on your Pwnagotchi. If you want to create other containers, repeat the same process and change the directory path and container name. -All you have to do now is reboot your pwnagotchi and connect to the hotspot to provide the decryption password. +All you have to do now is reboot your Pwnagotchi and connect to the hotspot to provide the decryption password. ```sh reboot now ``` -**Note: remember to delete the original compressed backup archive once you are sure that everything is working fine.** +**Note: Remember to delete the original compressed backup archive once you are sure that everything is working fine.** -**Note 2: if the decryption web server is not working, run [this](#fix-decryption-server-bug-in-evilsocket-image) command.** +**Note 2: If the decryption web server is not working, run [this](#fix-decryption-server-bug-in-evilsocket-image) command.**