chore: Updated readme

2025-12-17 05:54:21 +01:00 · 2024-01-30 19:12:36 +01:00
parent 299b071cbe
commit bfe987349c
6 changed files with 104 additions and 20 deletions
--- a/Cargo.lock
+++ b/Cargo.lock
@@ -1008,7 +1008,7 @@ dependencies = [

 [[package]]
 name = "pkdns"
-version = "0.1.0"
+version = "0.1.1"
 dependencies = [
 "any-dns",
 "clap",
--- a/Cargo.toml
+++ b/Cargo.toml
@@ -1,6 +1,6 @@
 [package]
 name = "pkdns"
-version = "0.1.0"
+version = "0.1.1"
 edition = "2021"

 # See more keys and their definitions at https://doc.rust-lang.org/cargo/reference/manifest.html
--- a/README.md
+++ b/README.md
@@ -1,17 +1,80 @@
 # pkdns

+![GitHub Release](https://img.shields.io/github/v/release/severinalexb/pkdns)
+
+
 DNS server resolving [pkarr](https://github.com/nuhvi/pkarr) self-sovereign domains.

 ## Getting Started

+### Hosted DNS
+
+Use one of the [hosted DNS servers](./servers.txt) to try out pkarr quickly.
+
+- [Verify](#verify-pkdns-is-working) the server is working.
+- [Configure](#change-your-system-dns) your system dns.
+- [Browse](#browse-the-self-sovereign-web) the self-sovereign web.


-### Build Yourself
+### Pre-Built Binaries
+1. Download the [latest release](https://github.com/SeverinAlexB/pkdns/releases/latest/) for your plattform.
+2. Extract the tar file. Should be something like `tar -xvf tarfile.tar.gz`.
+3. Run `pkdns -f 8.8.8.8`.
+4. [Verify](#verify-pkdns-is-working) the server is working.
+5. [Configure](#change-your-system-dns) your system dns.
+6. [Browse](#browse-the-self-sovereign-web) the self-sovereign web.

-1. Run `cargo run`.
-2. Configure you system to send DNS requests to `127.0.0.1:53`.
-3. Test by going to [http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/](http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/).

+### Build It Yourself
+
+Make sure you have the [Rust toolchain](https://rustup.rs/) installed.
+
+1. Clone repository `git clone https://github.com/SeverinAlexB/pkdns.git`.
+2. Switch directory `cd pkdns`.
+3. Run `cargo run -- -f 8.8.8.8`.
+4. [Verify](#verify-pkdns-is-working) the server is working.
+6. [Configure](#change-your-system-dns) your system dns to `127.0.0.1`.
+7. [Browse](#browse-the-self-sovereign-web) the self-sovereign web.
+
+
+## Guides
+
+### Change your System DNS
+
+Follow one of the guides to change your DNS server on your system:
+- [MacOS guide](https://support.apple.com/en-gb/guide/mac-help/mh14127)
+- [Ubuntu guide](https://www.ionos.com/digitalguide/server/configuration/change-dns-server-on-ubuntu/)
+- [Windows guide](https://www.windowscentral.com/how-change-your-pcs-dns-settings-windows-10)
+
+
+Verify your server with this domain [http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/](http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/).
+
+### Verify pkdns is working
+
+Verify the server resolves pkarr domains.
+Replace `PKDNS_SERVER_IP` with either a [hosted server ip](./servers.txt) or `127.0.0.1` if you run it on your localhost.
+
+```bash 
+nslookup 7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy PKDNS_SERVER_IP
+```
+
+> *Troubleshooting* If this does not work then the pkdns server is likely not running.
+
+Verify it resolves regular ICANN domains. Replace `PKDNS_SERVER_IP` with either a [hosted server ip](./servers.txt) or `127.0.0.1` if you run it on your localhost.
+
+```bash
+nslookup example.com PKDNS_SERVER_IP
+```
+
+> *Troubleshooting* If this does not work then you need to change your ICANN fallback server with
+> `pkdns -f REGULAR_DNS_SERVER_IP`. Or use the Google DNS server: `pkdns -f 8.8.8.8`.
+
+### Browse the Self-Sovereign Web
+
+Here are some example pkarr domains:
+
+- [http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/](http://7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/).
+- [http://pknames.p2p.7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/](http://pknames.p2p.7fmjpcuuzf54hw18bsgi3zihzyh4awseeuq5tmojefaezjbd64cy/).

 ## Options

@@ -28,3 +91,7 @@ Options:
  -h, --help                   Print help
  -V, --version                Print version
 ```
+
+
+
+May the power ⚡ be with you.
--- a/build.sh
+++ b/build.sh
@@ -1,12 +1,17 @@
 #!/bin/bash

+VERSION=$(cargo get package.version)
+echo pkdns $VERSION
 echo Build OSX amd64
 cargo build --release --package=pkdns
+echo
 echo Build Linux amd64
 cargo build --release --package=pkdns --target=x86_64-unknown-linux-gnu
+echo
 echo Build Windows amd64
 cargo build --release --package=pkdns --target=x86_64-pc-windows-gnu

+
 echo
 echo Build packets
 rm -rf target/github-release
@@ -14,23 +19,28 @@ cd target
 mkdir github-release

 echo Tar osx
-mkdir github-release/pknames-osx-amd64
-cp release/pkdns github-release/pknames-osx-amd64
-cd github-release && tar -czf pknames-osx-amd64.tar.gz pknames-osx-amd64 && cd ..
-rm -rf github-release/pknames-osx-amd64
+DIR_NAME="pkdns-osx-amd64-v$VERSION"
+mkdir github-release/$DIR_NAME
+cp release/pkdns github-release/$DIR_NAME
+cd github-release && tar -czf $DIR_NAME.tar.gz $DIR_NAME && cd ..
+rm -rf github-release/$DIR_NAME

 echo Tar linux
-mkdir github-release/pknames-linux-amd64
-cp x86_64-unknown-linux-gnu/release/pkdns github-release/pknames-linux-amd64
-cd github-release && tar -czf pknames-linux-amd64.tar.gz pknames-linux-amd64 && cd ..
-rm -rf github-release/pknames-linux-amd64
+DIR_NAME="pkdns-linux-amd64-v$VERSION"
+mkdir github-release/$DIR_NAME
+cp x86_64-unknown-linux-gnu/release/pkdns github-release/$DIR_NAME
+cd github-release && tar -czf $DIR_NAME.tar.gz $DIR_NAME && cd ..
+rm -rf github-release/$DIR_NAME

 echo Tar Windows
-mkdir github-release/pknames-windows-amd64
-cp x86_64-pc-windows-gnu/release/pkdns.exe github-release/pknames-windows-amd64
-cd github-release && tar -czf pknames-windows-amd64.tar.gz pknames-windows-amd64 && cd ..
-rm -rf github-release/pknames-windows-amd64
+DIR_NAME="pkdns-windows-amd64-v$VERSION"
+mkdir github-release/$DIR_NAME
+cp x86_64-pc-windows-gnu/release/pkdns.exe github-release/$DIR_NAME
+cd github-release && tar -czf $DIR_NAME.tar.gz $DIR_NAME && cd ..
+rm -rf github-release/$DIR_NAME

 echo
 cd ..
 tree target/github-release
+cd target/github-release
+pwd
--- a/servers.txt
+++ b/servers.txt
@@ -0,0 +1,3 @@
+# A list of free to use pkdns servers.
+
+37.27.13.182  # By lnrouter.app
--- a/src/main.rs
+++ b/src/main.rs
@@ -105,6 +105,10 @@ fn main() -> Result<(), Box<dyn Error>> {
    let threads: &String = matches.get_one("threads").unwrap();
    let threads: u8 = threads.parse().expect("threads should be valid positive integer.");
    let forward: &String = matches.get_one("forward").unwrap();
+    let mut forward: String = forward.clone();
+    if !forward.contains(":") {
+        forward.push_str(":53"); // Add default port
+    };
    let forward: SocketAddr = forward.parse().expect("forward should be valid IP:Port combination.");
    let socket: &String = matches.get_one("socket").unwrap();
    let socket: SocketAddr = socket.parse().expect("socket should be valid IP:Port combination.");