From 40974d296bcad3ba635979050856be897d4c76b2 Mon Sep 17 00:00:00 2001 From: John Dorman Date: Sun, 12 Jul 2020 22:37:04 -0700 Subject: [PATCH] Cleaning up Markdowns --- AdguardHome/README.md | 22 +++++---- README.md | 27 ++++++++--- nextdns/README.md | 23 ++++++--- on-boot-script/README.md | 48 ++++++++++++------- .../{README-MANUALmd => README.old.md} | 46 ++++++++++++------ run-pihole/README.md | 30 +++++++----- 6 files changed, 129 insertions(+), 67 deletions(-) rename on-boot-script/{README-MANUALmd => README.old.md} (76%) diff --git a/AdguardHome/README.md b/AdguardHome/README.md index 917955e..8968534 100644 --- a/AdguardHome/README.md +++ b/AdguardHome/README.md @@ -1,19 +1,23 @@ # Run AdguardHome on your UDM -### Features +## Features + 1. Run AdguardHome on your UDM with a completely isolated network stack. This will not port conflict or be influenced by any changes on by Ubiquiti 2. Persists through reboots and firmware updates. -### Requirements -1. You have setup the on boot script described [here](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script) -2. AdguardHome persists through firmware updates as it will store the configuration in a folder (you need to create this). It needs 2 folders, a Work and Configuration folder. Please create the 2 folders in "/mnt/data/". In my example I created "AdguardHome-Confdir" and "AdguardHome-Workdir" +## Requirements + +1. You have setup the on boot script described [here](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script) +1. AdguardHome persists through firmware updates as it will store the configuration in a folder (you need to create this). It needs 2 folders, a Work and Configuration folder. Please create the 2 folders in "/mnt/data/". In my example I created "AdguardHome-Confdir" and "AdguardHome-Workdir" + +## Customization -### Customization * Feel free to change [20-dns.conflist](../cni-plugins/20-dns.conflist) to change the IP address of the container. * Update [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) with your own values * If you want IPv6 support use [20-dnsipv6.conflist](../cni-plugins/20-dnsipv6.conflist) and update [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) with the IPv6 addresses. Also, please provide IPv6 servers to podman using --dns arguments. -### Steps +## Steps + 1. On your controller, make a Corporate network with no DHCP server and give it a VLAN. For this example we are using VLAN 5. 1. Copy [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) to /mnt/data/on_boot.d and update its values to reflect your environment 1. Execute /mnt/data/on_boot.d/10-dns.sh @@ -30,6 +34,6 @@ adguard/adguardhome:arm64-latest ``` -7. Browse to 10.0.5.3:3000 and follow the setup wizard -8. Update your DNS Servers to 10.0.5.3 (or your custom ip) in all your DHCP configs. -9. Access the AdguardHome like you would normally. +1. Browse to 10.0.5.3:3000 and follow the setup wizard +1. Update your DNS Servers to 10.0.5.3 (or your custom ip) in all your DHCP configs. +1. Access the AdguardHome like you would normally. diff --git a/README.md b/README.md index f23e4ca..371840e 100644 --- a/README.md +++ b/README.md @@ -1,49 +1,62 @@ -# udm-utilities [](https://join.slack.com/t/boostchicken/shared_invite/zt-fcjszaw4-2ZuNFxIQnrpjxixnm17LXQ) +# udm-utilities [![Slack](https://img.shields.io/badge/slack-boostchicken-blue.svg?logo=slack "Boostchicken Slack")](https://join.slack.com/t/boostchicken/shared_invite/zt-fcjszaw4-2ZuNFxIQnrpjxixnm17LXQ) A collection of things to enhance the capabilities of your Unifi Dream Machine or Dream Machine Pro. ## Contributing + Pull Requests welcome! If you use this functionality to do new cool stuff to your UDM/P please send a PR and share it with the community! ## General Tools + ### on-boot-script + Enables init.d style scripts to run on every boot of your UDM. Includes a wpa-supplicant/eap-proxy example. **It enables complete customization of your UDM/P and fills the gap that config.gateway.json left behind.** ### python + If you need python3 on your UDM, generally not recommended, can always use it in unifi-os container ## VPN Servers / Clients ### wireguard-go + Run a Wireguard client/server on your UDM/P. Utilizes wireguard-go, not linux kernel modules. The performance will take a hit due to that. ## DNS Providers + ### dns-common + Configurations for DNS containers, both IPv4 and IPv6. Utilizes MacVLAN CNI plugins to completely isolate the network stack. ### run-pihole + Run pihole on your UDM with podman. ### nextdns -Run NextDNS on your UDM with podman. + +Run NextDNS on your UDM with podman. ### AdguardHome + Run AdguardHome on your UDM with podman. ## Cool projects you can use with this -### multicast-relay -https://hub.docker.com/r/scyto/multicast-relay +### multicast-relay -This is a docker container that implements https://github.com/alsmith/multicast-relay to provide mDNS and SSDP on a unifi dream machine. It will likely work on any multi homed host. + + +This is a docker container that implements to provide mDNS and SSDP on a unifi dream machine. It will likely work on any multi homed host. ### ntopng -https://github.com/tusc/ntopng-udm + + Much better network stats for your UDM/P! Install this docker container and create an on_boot script to make sure it's always running. ### LetsEncrypt SSL Certs -https://github.com/kchristensen/udm-le + + Provision and renew LetsEncrypt SSL certs from your UDM/P diff --git a/nextdns/README.md b/nextdns/README.md index 3fe1015..0487967 100644 --- a/nextdns/README.md +++ b/nextdns/README.md @@ -1,34 +1,42 @@ # Run NextDNS on your UDM -### Features +## Features + 1. Run NextDNS on your UDM with a completely isolated network stack. This will not port conflict or be influenced by any changes on by Ubiquiti. 2. Resolves IP addresses handed out by DHCP on the UDM! 3. Persists through reboots and firmware updates. 4. If you are already using PiHole and want to test NextDNS out, you can just stop your PiHole container and start this one in its place using the same IP/CNI config. -### Requirements +## Requirements + 1. You have already setup the on boot script described [here](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script) -### Customization -* Feel free to change [20-dns.conflist](../cni-plugins/20-dns.conflist) to change the IP address of the container. +## Customization + +* Feel free to change [20-dns.conflist](../cni-plugins/20-dns.conflist) to change the IP address of the container. * The NextDNS docker image is not supported by NextDNS. It is built out of this repo. If you make any enhancements please contribute back via a Pull Request. * If you want to inject custom DNS names into NextDNS use --add-host docker commands. The /etc/resolv.conf and /etc/hosts is generated from that and --dns. * Edit [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) and update its values to reflect your environment (specifically the container name) * If you want IPv6 support use [20-dnsipv6.conflist](../cni-plugins/20-dnsipv6.conflist) and update [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) with the IPv6 addresses. Also, please provide IPv6 servers to podman using --dns arguments. -### Docker +## Docker + The official repo is boostchicken/nextdns-udm. Latest will always refer to the latest builds, there are also tags for each NextDNS release (e.g. 1.6.4). The Dockerfile is included, you can build it locally on your UDM if you don't want to pull from Docker Hub or make customizations + ```shell script podman build . -t nextdns-udm:latest ``` + Building from another device is possible. You must have [buildx](https://github.com/docker/buildx/) installed to do cross platform builds. This is useful if you want to mirror to a private repo + ```shell script docker buildx build --platform linux/arm64/v8 -t nextdns-udm:latest . ``` -### Steps +## Steps + If you have already installed PiHole, skip right to step 6. 1. On your controller, make a Corporate network with no DHCP server and give it a VLAN. For this example we are using VLAN 5. @@ -37,6 +45,7 @@ If you have already installed PiHole, skip right to step 6. 4. Copy [20-dns.conflist](../cni-plugins/20-dns.conflist) to /mnt/data/podman/cni. This will create your podman macvlan network 5. Create /mnt/data/nextdns and copy [nextdns.conf](udm-files/nextdns.conf) to it. 6. Run the NextDNS docker container. Mounting dbus and running in privileged is only required for mDNS. Also, please change the --dns arguments to whatever was provided by NextDNS. + ```shell script podman run -d -it --privileged --network dns --restart always \ --name nextdns \ @@ -47,5 +56,5 @@ If you have already installed PiHole, skip right to step 6. --hostname nextdns \ boostchicken/nextdns-udm:latest ``` -7. Update your DNS Servers to 10.0.5.3 (or your custom ip) in all your DHCP configs. +7. Update your DNS Servers to 10.0.5.3 (or your custom ip) in all your DHCP configs. diff --git a/on-boot-script/README.md b/on-boot-script/README.md index 6fac777..d099c05 100644 --- a/on-boot-script/README.md +++ b/on-boot-script/README.md @@ -1,45 +1,57 @@ # UDM / UDMPro Boot Script -### Features + +## Features + 1. Allows you to run a shell script at S95 anytime your UDM starts / reboots 1. Persists through reboot and **firmware updates**! It is able to do this because Ubiquiti caches all debian package installs on the UDM in /mnt/data, then re-installs them on every boot +## Compatibility -### Compatibility 1. Should work on any UDM/UDMPro after 1.6.3 2. Tested and confirmed on 1.6.6, 1.7.0, 1.7.2rc4, 1.7.3rc1 ### Upgrade from earlier way + * As long as you didn't change the filenames, installing the deb package is all you need to do. If you want to clean up beforehand anyways.... -``` -rm /etc/init.d/udm.sh -systemctl disable udmboot -rm /etc/systemd/system/udmboot.service -``` + + ```bash + rm /etc/init.d/udm.sh + systemctl disable udmboot + rm /etc/systemd/system/udmboot.service + ``` + * The new package is exactly the old steps packaged in a debian package * [dpkg-build-files](dpkg-build-files) contains the scripts that build the package (using dh_make and debuild) if you want to build it yourself / change it * Built on Ubuntu-20.04 on Windows 10/WSL2 ## Steps + 1. Get into the unifios shell on your udm -```shell script -unifi-os shell -``` + + ```bash + unifi-os shell + ``` + 2. Download [udm-boot_1.0.1-1_all.deb](packages/udm-boot_1.0.1-1_all.deb) and install it and go back to the UDM -```shell script -curl -L https://raw.githubusercontent.com/boostchicken/udm-utilities/master/on-boot-script/packages/udm-boot_1.0.1-1_all.deb -o udm-boot_1.0.1-1_all.deb -dpkg -i udm-boot_1.0.1-1_all.deb -exit -``` + + ```bash + curl -L https://raw.githubusercontent.com/boostchicken/udm-utilities/master/on-boot-script/packages/udm-boot_1.0.1-1_all.deb -o udm-boot_1.0.1-1_all.deb + dpkg -i udm-boot_1.0.1-1_all.deb + exit + ``` + 3. Copy any shell scripts you want to run to /mnt/data/on_boot.d on your UDM (not the unifi-os shell)and make sure they are executable and have the correct shebang (#!/bin/sh) - Examples: + + Examples: * Start a DNS Container [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) * Start wpa_supplicant [on_boot.d/10-wpa_supplicant.sh](examples/udm-files/on_boot.d/10-wpa_supplicant.sh) - ## Version History ### 1.0.1 + * Fully automated install, all that is left is populating /mnt/data/on_boot.d ### 1.0.0 -* First release that persists through firmware \ No newline at end of file + +* First release that persists through firmware diff --git a/on-boot-script/README-MANUALmd b/on-boot-script/README.old.md similarity index 76% rename from on-boot-script/README-MANUALmd rename to on-boot-script/README.old.md index 6e2b8e3..2af6464 100644 --- a/on-boot-script/README-MANUALmd +++ b/on-boot-script/README.old.md @@ -1,5 +1,8 @@ +# Legacy setup + +## Automated Setup + * NB! THESE WILL NOT PERSIST THROUGH FIRMWARE. They still work however -### Automated Setup 1. Copy [install.sh](manual-install/install.sh) to your UDM and execute it 1. Copy any shell scripts you want to run to /mnt/data/on_boot.d and make sure they are executable and have the correct shebang (#!/bin/sh) @@ -7,29 +10,36 @@ * Start a DNS Container [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) * Start wpa_supplicant [on_boot.d/10-wpa_supplicant.sh](examples/udm-files/on_boot.d/10-start-containers.sh) -### Manual Setup +## Manual Setup 1. Copy on_boot.sh and make on_boot.d and add scripts to on_boot.d - ```shell script + + ```sh mkdir -p /mnt/data/on_boot.d vi /mnt/data/on_boot.sh chmod u+x /mnt/data/on_boot.sh ``` + Example: [on_boot.sh](examples/udm-files/on_boot.sh) -1. Enter the container shell - ```shell script +2. Enter the container shell + + ```sh unifi-os shell ``` -1. make a script that sshs to the udm and runs on our boot script. 127.0.1.1 always points to the UDM - ```shell script + +3. make a script that sshs to the udm and runs on our boot script. 127.0.1.1 always points to the UDM + + ```sh echo "#!/bin/sh ssh -o StrictHostKeyChecking=no root@127.0.1.1 '/mnt/data/on_boot.sh'" > /etc/init.d/udm.sh chmod u+x /etc/init.d/udm.sh ``` + Example: [udm.sh](examples/unifi-os-files/udm.sh) -1. make a service that runs on startup, after we have networking - ```shell script +4. make a service that runs on startup, after we have networking + + ```sh echo "[Unit] Description=Run On Startup UDM After=network.target @@ -40,19 +50,25 @@ [Install] WantedBy=multi-user.target" > /etc/systemd/system/udmboot.service ``` + Example: [udmboot.service](examples/unifi-os-files/udmboot.service) -1. enable it and test - ```shell script +5. enable it and test + + ```sh systemctl enable udmboot systemctl start udmboot ``` -1. back to the udm - ```shell script + +6. back to the udm + + ```sh exit ``` -1. reboot your udm/udmpro and make sure it worked - ```shell script + +7. reboot your udm/udmpro and make sure it worked + + ```sh reboot exit ``` diff --git a/run-pihole/README.md b/run-pihole/README.md index b5cf7f0..1e67345 100644 --- a/run-pihole/README.md +++ b/run-pihole/README.md @@ -1,25 +1,29 @@ # Run PiHole on your UDM -### Features +## Features + 1. Run PiHole on your UDM with a completely isolated network stack. This will not port conflict or be influenced by any changes on by Ubiquiti 2. Persists through reboots and firmware updates. -### Requirements +## Requirements + 1. You have successfully setup the on boot script described [here](https://github.com/boostchicken/udm-utilities/tree/master/on-boot-script) -### Customization +## Customization + * Feel free to change [20-dns.conflist](../cni-plugins/20-dns.conflist) to change the IP address of the container. * Update [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) with your own values * If you want IPv6 support use [20-dnsipv6.conflist](../cni-plugins/20-dnsipv6.conflist) and update [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) with the IPv6 addresses. Also, please provide IPv6 servers to podman using --dns arguments. -### Steps +## Steps + 1. On your controller, make a Corporate network with no DHCP server and give it a VLAN. For this example we are using VLAN 5. 2. Copy [10-dns.sh](../dns-common/on_boot.d/10-dns.sh) to /mnt/data/on_boot.d and update its values to reflect your environment 3. Execute /mnt/data/on_boot.d/10-dns.sh 4. Copy [20-dns.conflist](../cni-plugins/20-dns.conflist) to /mnt/data/podman/cni. This will create your podman macvlan network 5. Run the pihole docker container, be sure to make the directories for your persistent pihole configuration. They are mounted as volumes in the command below. - ```shell script + ```sh podman run -d --network dns --restart always \ --name pihole \ -e TZ="America/Los Angeles" \ @@ -33,15 +37,19 @@ -e IPv6="False" \ pihole/pihole:latest ``` - + The below errors are expected and acceptable - ``` + + ```sh ERRO[0022] unable to get systemd connection to add healthchecks: dial unix /run/systemd/private: connect: no such file or directory ERRO[0022] unable to get systemd connection to start healthchecks: dial unix /run/systemd/private: connect: no such file or directory ``` -7. Set pihole password - ```shell script + +6. Set pihole password + + ```sh podman exec -it pihole pihole -a -p YOURNEWPASSHERE ``` -8. Update your DNS Servers to 10.0.5.3 (or your custom ip) in all your DHCP configs. -9. Access the pihole like you would normally. + +7. Update your DNS Servers to 10.0.5.3 (or your custom ip) in all your DHCP configs. +8. Access the pihole like you would normally.