fix(docs): Totally redesign the readme
Also, use the American spelling of LICENSE instead of LICENCE since that is what everyone else already does
This commit is contained in:
parent
20f5b21be1
commit
835cb8c950
GPG key ID:
4D8B07C18F31ACBD
4 changed files with 149 additions and 92 deletions
|
|
@ -19,7 +19,7 @@ builds:
|
|||
|
||||
archives:
|
||||
- files:
|
||||
- LICENCE
|
||||
- LICENSE
|
||||
- completions/**
|
||||
- doc/awl.1.gz
|
||||
name_template: >-
|
||||
|
|
@ -133,7 +133,7 @@ nfpms:
|
|||
dst: /usr/share/bash-completion/completions/awl
|
||||
- src: doc/awl.1.gz
|
||||
dst: /usr/share/man/man1/awl.1.gz
|
||||
- src: LICENCE
|
||||
- src: license
|
||||
dst: /usr/share/doc/awl/copyright
|
||||
- src: completions/fish.fish
|
||||
dst: /usr/share/fish/vendor_completions.d/awl.fish
|
||||
|
|
|
|||
|
|
@ -1,11 +1,11 @@
|
|||
Copyright 2022 Sam Therapy, Gregward Bulon
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
||||
|
||||
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
|
||||
|
||||
Copyright 2022 Sam Therapy, Gregward Bulon
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
|
||||
1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
||||
|
||||
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
||||
|
||||
3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
217
README.md
217
README.md
|
|
@ -1,105 +1,162 @@
|
|||
# awl
|
||||
# <img src="./doc/awl-text.png" width="50%" title="awl logo" alt="awl">
|
||||
|
||||
[](https://ci.git.froth.zone/sam/awl)
|
||||
> awl *(noun)*: A pointed tool for making small holes in wood or leather
|
||||
|
||||
`awl` is a command-line DNS client, much like
|
||||
[`drill`](https://github.com/NLnetLabs/ldns),
|
||||
[`dig`](https://bind9.readthedocs.io/en/v9_18_3/manpages.html#dig-dns-lookup-utility),
|
||||
[`dog`](https://github.com/ogham/dog),
|
||||
[`doggo`](https://github.com/mr-karan/doggo), or
|
||||
[`q`](https://github.com/natesales/q).
|
||||
|
||||
`awl` is designed to be a drop-in replacement for the venerable dig, but support
|
||||
newer RFC query types, such as DNS-over-HTTPS and DNS-over-QUIC.
|
||||
A command-line DNS lookup tool that supports DNS queries over UDP, TCP, TLS, HTTPS, DNSCrypt, and QUIC.
|
||||
|
||||
## Usage
|
||||
|
||||
- [Feature wiki](https://git.froth.zone/sam/awl/wiki/Supported)
|
||||
- [Manpage](https://git.froth.zone/sam/awl/wiki/awl.1)
|
||||
[](https://git.froth.zone/sam/awl)
|
||||
[](https://git.froth.zone/sam/awl/commits/branch/master)
|
||||
[](https://goreportcard.com/report/dns.froth.zone/awl)
|
||||
[](https://spdx.org/licenses/BSD-3-Clause.html)
|
||||
|
||||
## Building and installing
|
||||
|
||||
### From releases
|
||||
Awl is designed to be a drop-in replacement for [dig](https://bind9.readthedocs.io/en/v9_18_3/manpages.html#dig-dns-lookup-utility).
|
||||
|
||||
Grab a prebuilt binary from the
|
||||
[release](https://git.froth.zone/sam/awl/releases) section.
|
||||
## Examples
|
||||
|
||||
### Package Managers
|
||||
```shell
|
||||
# Query a domain over UDP
|
||||
awl example.com
|
||||
|
||||
- AUR: [awl-dns-git](https://aur.archlinux.org/packages/awl-dns-git)
|
||||
- Debian/Ubuntu (any .deb consuming distro should work):
|
||||
# Query a domain over TCP
|
||||
awl example.com
|
||||
|
||||
```sh
|
||||
# Add PGP key
|
||||
sudo curl https://git.froth.zone/api/packages/sam/debian/repository.key -o /usr/share/keyrings/git-froth-zone-sam.asc
|
||||
# Add repo
|
||||
echo "deb [signed-by=/usr/share/keyrings/git-froth-zone-sam.asc] https://git.froth.zone/api/packages/sam/debian sid main" | sudo tee /etc/apt/sources.list.d/git-froth-zone-sam.list
|
||||
sudo apt update
|
||||
sudo apt install awl-dns
|
||||
```
|
||||
# Query a domain over TLS, print as JSON
|
||||
awl example.com +tls +json
|
||||
```
|
||||
|
||||
- Fedora (any .rpm consuming distro should work [but will run into problems updating, not recommended](https://git.froth.zone/sam/awl/issues/197)):
|
||||
For more and the usage, see the [manpage](/wiki/awl.1).
|
||||
|
||||
```sh
|
||||
echo '[git-froth-zone-sam]
|
||||
name=sam - Froth Git
|
||||
baseurl=https://git.froth.zone/api/packages/sam/rpm
|
||||
enabled=1
|
||||
gpgcheck=0
|
||||
gpgkey=https://git.froth.zone/api/packages/sam/rpm/repository.key' | sudo tee /etc/yum.repos.d/git-froth-zone-sam.repo
|
||||
sudo yum install awl-dns
|
||||
```
|
||||
## Installing
|
||||
|
||||
- Alpine (any .apk consuming distro should work):
|
||||
On any platform, with [Go](https://go.dev) installed, run the following command to install:
|
||||
|
||||
```sh
|
||||
echo "https://git.froth.zone/api/packages/sam/alpine/edge/main" | sudo tee -a /etc/apk/repositories
|
||||
sudo curl -JO https://git.froth.zone/api/packages/sam/alpine/key --output-dir /etc/apk/keys
|
||||
sudo apk add awl-dns
|
||||
```
|
||||
|
||||
- Homebrew:
|
||||
|
||||
```sh
|
||||
brew install SamTherapy/tap/awl
|
||||
```
|
||||
|
||||
- Scoop:
|
||||
|
||||
```pwsh
|
||||
scoop bucket add froth https://git.froth.zone/packages/scoop.git
|
||||
scoop install awl
|
||||
```
|
||||
|
||||
### From source
|
||||
|
||||
Dependencies:
|
||||
|
||||
- [Go](https://go.dev/) >= 1.20
|
||||
- GNU/BSD make or Plan 9 mk (if using the makefile/mkfile)
|
||||
- [scdoc](https://git.sr.ht/~sircmpwn/scdoc) (optional, for man page)
|
||||
|
||||
Using `go install`:
|
||||
|
||||
```sh
|
||||
```shell
|
||||
go install dns.froth.zone/awl@latest
|
||||
```
|
||||
|
||||
Using the makefile:
|
||||
Alternatively, many package managers are supported:
|
||||
|
||||
```sh
|
||||
make && sudo make install
|
||||
<details>
|
||||
<summary>Linux</summary>
|
||||
|
||||
<details>
|
||||
<summary>Alpine Linux</summary>
|
||||
|
||||
Provided by [Gitea packages](https://git.froth.zone/sam/-/packages/alpine/awl-dns) \
|
||||
***Any distro that uses apk should also work***
|
||||
|
||||
```shell
|
||||
# Add the repository
|
||||
echo "https://git.froth.zone/api/packages/sam/alpine/edge/main" | tee -a /etc/apk/repositories
|
||||
# Get the signing key
|
||||
curl -JO https://git.froth.zone/api/packages/sam/alpine/key --output-dir /etc/apk/keys
|
||||
# Install
|
||||
apk add awl-dns
|
||||
```
|
||||
|
||||
## Contributing
|
||||
</details>
|
||||
|
||||
Send a [pull request](https://git.froth.zone/sam/awl/pulls) our way. Prefer
|
||||
emails? Send a patch to the
|
||||
[mailing list](https://lists.sr.ht/~sammefishe/awl-devel).
|
||||
<details>
|
||||
<summary>Arch</summary>
|
||||
|
||||
Found a bug or want a new feature? Create an issue
|
||||
[here](https://git.froth.zone/sam/awl/issues).
|
||||
AUR package available as [awl-dns-git](https://aur.archlinux.org/packages/awl-dns-git/)
|
||||
```shell
|
||||
yay -S awl-dns-git ||
|
||||
paru -S awl-dns-git
|
||||
```
|
||||
|
||||
### Licence
|
||||
</details>
|
||||
|
||||
Revised BSD, See [LICENCE](./LICENCE)
|
||||
<details>
|
||||
<summary>Debian / Ubuntu</summary>
|
||||
|
||||
Provided by [Gitea packages](https://git.froth.zone/sam/-/packages/debian/awl-dns/) \
|
||||
***Any distro that uses deb/dpkg should also work***
|
||||
|
||||
```shell
|
||||
# Add PGP key
|
||||
sudo curl https://git.froth.zone/api/packages/sam/debian/repository.key -o /usr/share/keyrings/git-froth-zone-sam.asc
|
||||
# Add repo
|
||||
echo "deb [signed-by=/usr/share/keyrings/git-froth-zone-sam.asc] https://git.froth.zone/api/packages/sam/debian sid main" | sudo tee /etc/apt/sources.list.d/git-froth-zone-sam.list
|
||||
# Update and install
|
||||
sudo apt update
|
||||
sudo apt install awl-dns
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Fedora / RHEL / SUSE</summary>
|
||||
|
||||
Provided by [Gitea packages](https://git.froth.zone/sam/-/packages/rpm/awl-dns/) \
|
||||
***Any distro that uses rpm/dnf might also work, I've never tried it***
|
||||
|
||||
```shell
|
||||
# Add the repository
|
||||
dnf config-manager --add-repo https://git.froth.zone/api/packages/sam/rpm.repo ||
|
||||
zypper addrepo https://git.froth.zone/api/packages/sam/rpm.repo
|
||||
# Install
|
||||
dnf install awl-dns ||
|
||||
zypper install awl-dns
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary>Gentoo</summary>
|
||||
|
||||
```shell
|
||||
# Add the ebuild repository
|
||||
eselect repository add froth-zone git https://git.froth.zone/packaging/portage.git
|
||||
emaint sync -r froth-zone
|
||||
# Install
|
||||
emerge -av net-dns/awl
|
||||
```
|
||||
|
||||
</details>
|
||||
|
||||
<details>
|
||||
<summary><a href="https://brew.sh" nofollow>Homebrew</a></summary>
|
||||
|
||||
```shell
|
||||
brew install SamTherapy/tap/awl
|
||||
```
|
||||
|
||||
</details>
|
||||
</details>
|
||||
<br />
|
||||
|
||||
<details>
|
||||
<summary>macOS</summary>
|
||||
|
||||
<details open>
|
||||
<summary><a href="https://brew.sh" nofollow>Homebrew</a></summary>
|
||||
|
||||
```shell
|
||||
brew install SamTherapy/tap/awl
|
||||
```
|
||||
</details>
|
||||
</details>
|
||||
<br />
|
||||
|
||||
<details>
|
||||
<summary>Windows</summary>
|
||||
|
||||
<details open>
|
||||
<summary><a href="https://scoop.sh" nofollow>Scoop</a></summary>
|
||||
|
||||
```pwsh
|
||||
scoop bucket add froth https://git.froth.zone/packages/scoop.git
|
||||
scoop install awl
|
||||
```
|
||||
</details>
|
||||
</details>
|
||||
|
||||
## License
|
||||
[BSD-3-Clause](https://spdx.org/licenses/BSD-3-Clause.html)
|
||||
|
||||
### Credits
|
||||
- Awl image taken from [Wikimedia Commons](https://commons.wikimedia.org/wiki/File:Awl.tif), imaged is licensed CC0.
|
||||
|
|
|
|||
BIN
doc/awl-text.png
Normal file
BIN
doc/awl-text.png
Normal file
Binary file not shown.
|
After Width: | Height: | Size: 195 KiB |
Loading…
Reference in a new issue