From 046ec13fdc5ec008fd4ac9b77cc943a96be2605c Mon Sep 17 00:00:00 2001 From: Ainar Garipov Date: Fri, 20 Nov 2020 18:06:07 +0300 Subject: [PATCH] Pull request: all: reformat yaml, add yaml formatting standard Merge in DNS/adguard-home from 2297-yaml to master Closes #2297. Squashed commit of the following: commit 85df3a38a14adb1965944ddf14b197c12a213057 Author: Ainar Garipov Date: Fri Nov 20 17:52:22 2020 +0300 all: improve HACKING.md commit 079acdfe41cc12ab6aa13d7c28dcbf7b7b3c8380 Merge: 202ea078e 3045da174 Author: Ainar Garipov Date: Fri Nov 20 17:50:34 2020 +0300 Merge branch 'master' into 2297-yaml commit 202ea078e29d88871a32ac6e668dfae6db802bab Author: Ainar Garipov Date: Thu Nov 12 20:25:42 2020 +0300 all: reformat yaml, add yaml formatting standard --- .codecov.yml | 16 +- .github/stale.yml | 32 +- .github/workflows/build.yml | 296 ++- .github/workflows/lint.yml | 93 +- .golangci.yml | 115 +- .goreleaser.yml | 199 +- HACKING.md | 42 +- openapi/openapi.yaml | 4045 ++++++++++++++++++----------------- 8 files changed, 2427 insertions(+), 2411 deletions(-) diff --git a/.codecov.yml b/.codecov.yml index f91e5c1f..8a3d121b 100644 --- a/.codecov.yml +++ b/.codecov.yml @@ -1,8 +1,8 @@ -coverage: - status: - project: - default: - target: 40% - threshold: null - patch: false - changes: false +'coverage': + 'status': + 'project': + 'default': + 'target': '40%' + 'threshold': null + 'patch': false + 'changes': false diff --git a/.github/stale.yml b/.github/stale.yml index fa56e823..90e24289 100644 --- a/.github/stale.yml +++ b/.github/stale.yml @@ -1,19 +1,19 @@ -# Number of days of inactivity before an issue becomes stale -daysUntilStale: 60 -# Number of days of inactivity before a stale issue is closed -daysUntilClose: 7 -# Issues with these labels will never be considered stale -exemptLabels: - - 'bug' - - 'enhancement' - - 'feature request' - - 'localization' -# Label to use when marking an issue as stale -staleLabel: 'wontfix' -# Comment to post when marking an issue as stale. Set to `false` to disable -markComment: > +# Number of days of inactivity before an issue becomes stale. +'daysUntilStale': 60 +# Number of days of inactivity before a stale issue is closed. +'daysUntilClose': 7 +# Issues with these labels will never be considered stale. +'exemptLabels': +- 'bug' +- 'enhancement' +- 'feature request' +- 'localization' +# Label to use when marking an issue as stale. +'staleLabel': 'wontfix' +# Comment to post when marking an issue as stale. Set to `false` to disable. +'markComment': > This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions. -# Comment to post when closing a stale issue. Set to `false` to disable -closeComment: false +# Comment to post when closing a stale issue. Set to `false` to disable. +'closeComment': false diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml index 0c599dbd..b59df4b1 100644 --- a/.github/workflows/build.yml +++ b/.github/workflows/build.yml @@ -1,170 +1,136 @@ -name: build +'name': 'build' -env: - GO_VERSION: 1.14 - NODE_VERSION: 13 +'env': + 'GO_VERSION': '1.14' + 'NODE_VERSION': '13' -on: - push: - branches: - - '*' - tags: - - v* - pull_request: +'on': + 'push': + 'branches': + - '*' + 'tags': + - 'v*' + 'pull_request': -jobs: +'jobs': + 'test': + 'runs-on': '${{ matrix.os }}' + 'env': + 'GO111MODULE': 'on' + 'GOPROXY': 'https://goproxy.io' + 'strategy': + 'fail-fast': false + 'matrix': + 'os': + - 'ubuntu-latest' + - 'macOS-latest' + - 'windows-latest' + 'steps': + - 'name': 'Checkout' + 'uses': 'actions/checkout@v2' + 'with': + 'fetch-depth': 0 + - 'name': 'Set up Go' + 'uses': 'actions/setup-go@v2' + 'with': + 'go-version': '${{ env.GO_VERSION }}' + - 'name': 'Set up Node' + 'uses': 'actions/setup-node@v1' + 'with': + 'node-version': '${{ env.NODE_VERSION }}' + - 'name': 'Set up Go modules cache' + 'uses': 'actions/cache@v2' + 'with': + 'path': '~/go/pkg/mod' + 'key': "${{ runner.os }}-go-${{ hashFiles('go.sum') }}" + 'restore-keys': '${{ runner.os }}-go-' + - 'name': 'Get npm cache directory' + 'id': 'npm-cache' + 'run': 'echo "::set-output name=dir::$(npm config get cache)"' + - 'name': 'Set up npm cache' + 'uses': 'actions/cache@v2' + 'with': + 'path': '${{ steps.npm-cache.outputs.dir }}' + 'key': "${{ runner.os }}-node-${{ hashFiles('client/package-lock.json') }}" + 'restore-keys': '${{ runner.os }}-node-' + - 'name': 'Run make ci' + 'shell': 'bash' + 'run': 'make ci' + - 'name': 'Upload coverage' + 'uses': 'codecov/codecov-action@v1' + 'if': "success() && matrix.os == 'ubuntu-latest'" + 'with': + 'token': '${{ secrets.CODECOV_TOKEN }}' + 'file': './coverage.txt' + 'app': + 'runs-on': 'ubuntu-latest' + 'needs': 'test' + 'steps': + - 'name': 'Checkout' + 'uses': 'actions/checkout@v2' + 'with': + 'fetch-depth': 0 + - 'name': 'Set up Go' + 'uses': 'actions/setup-go@v2' + 'with': + 'go-version': '${{ env.GO_VERSION }}' + - 'name': 'Set up Node' + 'uses': 'actions/setup-node@v1' + 'with': + 'node-version': '${{ env.NODE_VERSION }}' + - 'name': 'Set up Go modules cache' + 'uses': 'actions/cache@v2' + 'with': + 'path': '~/go/pkg/mod' + 'key': "${{ runner.os }}-go-${{ hashFiles('go.sum') }}" + 'restore-keys': '${{ runner.os }}-go-' + - 'name': 'Get npm cache directory' + 'id': 'npm-cache' + 'run': 'echo "::set-output name=dir::$(npm config get cache)"' + - 'name': 'Set up node_modules cache' + 'uses': 'actions/cache@v2' + 'with': + 'path': '${{ steps.npm-cache.outputs.dir }}' + 'key': "${{ runner.os }}-node-${{ hashFiles('client/package-lock.json') }}" + 'restore-keys': '${{ runner.os }}-node-' + - 'name': 'Set up Snapcraft' + 'run': 'sudo apt-get -yq --no-install-suggests --no-install-recommends install snapcraft' + - 'name': 'Set up GoReleaser' + 'run': 'curl -sfL https://install.goreleaser.com/github.com/goreleaser/goreleaser.sh | BINDIR="$(go env GOPATH)/bin" sh' + - 'name': 'Run snapshot build' + 'run': 'make release' - test: - runs-on: ${{ matrix.os }} - env: - GO111MODULE: on - GOPROXY: https://goproxy.io - strategy: - fail-fast: false - matrix: - os: - - ubuntu-latest - - macOS-latest - - windows-latest - steps: - - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - - name: Set up Go - uses: actions/setup-go@v2 - with: - go-version: ${{ env.GO_VERSION }} + 'docker': + 'runs-on': 'ubuntu-latest' + 'needs': 'test' + 'steps': + - 'name': 'Checkout' + 'uses': 'actions/checkout@v2' + 'with': + 'fetch-depth': 0 + - 'name': 'Set up QEMU' + 'uses': 'docker/setup-qemu-action@v1' + - 'name': 'Set up Docker Buildx' + 'uses': 'docker/setup-buildx-action@v1' + - 'name': 'Docker Buildx (build)' + 'run': 'make docker-multi-arch' - - - name: Set up Node - uses: actions/setup-node@v1 - with: - node-version: ${{ env.NODE_VERSION }} - - - name: Set up Go modules cache - uses: actions/cache@v2 - with: - path: ~/go/pkg/mod - key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }} - restore-keys: | - ${{ runner.os }}-go- - - - name: Get npm cache directory - id: npm-cache - run: | - echo "::set-output name=dir::$(npm config get cache)" - - - name: Set up npm cache - uses: actions/cache@v2 - with: - path: ${{ steps.npm-cache.outputs.dir }} - key: ${{ runner.os }}-node-${{ hashFiles('client/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-node- - - - name: Run make ci - shell: bash - run: | - make ci - - - name: Upload coverage - uses: codecov/codecov-action@v1 - if: success() && matrix.os == 'ubuntu-latest' - with: - token: ${{ secrets.CODECOV_TOKEN }} - file: ./coverage.txt - - app: - runs-on: ubuntu-latest - needs: test - steps: - - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - - name: Set up Go - uses: actions/setup-go@v2 - with: - go-version: ${{ env.GO_VERSION }} - - - name: Set up Node - uses: actions/setup-node@v1 - with: - node-version: ${{ env.NODE_VERSION }} - - - name: Set up Go modules cache - uses: actions/cache@v2 - with: - path: ~/go/pkg/mod - key: ${{ runner.os }}-go-${{ hashFiles('go.sum') }} - restore-keys: | - ${{ runner.os }}-go- - - - name: Get npm cache directory - id: npm-cache - run: | - echo "::set-output name=dir::$(npm config get cache)" - - - name: Set up node_modules cache - uses: actions/cache@v2 - with: - path: ${{ steps.npm-cache.outputs.dir }} - key: ${{ runner.os }}-node-${{ hashFiles('client/package-lock.json') }} - restore-keys: | - ${{ runner.os }}-node- - - - name: Set up Snapcraft - run: | - sudo apt-get -yq --no-install-suggests --no-install-recommends install snapcraft - - - name: Set up GoReleaser - run: | - curl -sfL https://install.goreleaser.com/github.com/goreleaser/goreleaser.sh | BINDIR="$(go env GOPATH)/bin" sh - - - name: Run snapshot build - run: | - make release - - docker: - runs-on: ubuntu-latest - needs: test - steps: - - - name: Checkout - uses: actions/checkout@v2 - with: - fetch-depth: 0 - - - name: Set up QEMU - uses: docker/setup-qemu-action@v1 - - - name: Set up Docker Buildx - uses: docker/setup-buildx-action@v1 - - - name: Docker Buildx (build) - run: | - make docker-multi-arch - - notify: - needs: [app, docker] - # Secrets are not passed to workflows that are triggered by a pull request from a fork - if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }} - runs-on: ubuntu-latest - steps: - - - name: Conclusion - uses: technote-space/workflow-conclusion-action@v1 - - - name: Send Slack notif - uses: 8398a7/action-slack@v3 - with: - status: ${{ env.WORKFLOW_CONCLUSION }} - fields: repo,message,commit,author - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} + 'notify': + 'needs': + - 'app' + - 'docker' + # Secrets are not passed to workflows that are triggered by a pull request + # from a fork. + 'if': "${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}" + 'runs-on': 'ubuntu-latest' + 'steps': + - 'name': 'Conclusion' + 'uses': 'technote-space/workflow-conclusion-action@v1' + - 'name': 'Send Slack notif' + 'uses': '8398a7/action-slack@v3' + 'with': + 'status': '${{ env.WORKFLOW_CONCLUSION }}' + 'fields': 'repo, message, commit, author' + 'env': + 'GITHUB_TOKEN': '${{ secrets.GITHUB_TOKEN }}' + 'SLACK_WEBHOOK_URL': '${{ secrets.SLACK_WEBHOOK_URL }}' diff --git a/.github/workflows/lint.yml b/.github/workflows/lint.yml index 71de1b4f..b48b508b 100644 --- a/.github/workflows/lint.yml +++ b/.github/workflows/lint.yml @@ -1,47 +1,46 @@ -name: golangci-lint -on: - push: - tags: - - v* - branches: - - '*' - pull_request: -jobs: - golangci: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: golangci-lint - uses: golangci/golangci-lint-action@v2.3.0 - with: - # Required: the version of golangci-lint is required and must be specified without patch version: we always use the latest patch version. - version: v1.32 - - eslint: - runs-on: ubuntu-latest - steps: - - uses: actions/checkout@v2 - - name: Install modules - run: npm --prefix client ci - - name: Run ESLint - run: npm --prefix client run lint - - - notify: - needs: [golangci,eslint] - # Secrets are not passed to workflows that are triggered by a pull request from a fork - if: ${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }} - runs-on: ubuntu-latest - steps: - - - name: Conclusion - uses: technote-space/workflow-conclusion-action@v1 - - - name: Send Slack notif - uses: 8398a7/action-slack@v3 - with: - status: ${{ env.WORKFLOW_CONCLUSION }} - fields: repo,message,commit,author - env: - GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} - SLACK_WEBHOOK_URL: ${{ secrets.SLACK_WEBHOOK_URL }} +'name': 'golangci-lint' +'on': + 'push': + 'tags': + - 'v*' + 'branches': + - '*' + 'pull_request': +'jobs': + 'golangci': + 'runs-on': 'ubuntu-latest' + 'steps': + - 'uses': 'actions/checkout@v2' + - 'name': 'golangci-lint' + 'uses': 'golangci/golangci-lint-action@v2.3.0' + 'with': + # This field is required. Don't set the patch version to always use + # the latest patch version. + 'version': 'v1.32' + 'eslint': + 'runs-on': 'ubuntu-latest' + 'steps': + - 'uses': 'actions/checkout@v2' + - 'name': 'Install modules' + 'run': 'npm --prefix client ci' + - 'name': 'Run ESLint' + 'run': 'npm --prefix client run lint' + 'notify': + 'needs': + - 'golangci' + - 'eslint' + # Secrets are not passed to workflows that are triggered by a pull request + # from a fork. + 'if': "${{ github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository }}" + 'runs-on': 'ubuntu-latest' + 'steps': + - 'name': 'Conclusion' + 'uses': 'technote-space/workflow-conclusion-action@v1' + - 'name': 'Send Slack notif' + 'uses': '8398a7/action-slack@v3' + 'with': + 'status': '${{ env.WORKFLOW_CONCLUSION }}' + 'fields': 'repo, message, commit, author' + 'env': + 'GITHUB_TOKEN': '${{ secrets.GITHUB_TOKEN }}' + 'SLACK_WEBHOOK_URL': '${{ secrets.SLACK_WEBHOOK_URL }}' diff --git a/.golangci.yml b/.golangci.yml index 29ec1f4e..19402bd9 100644 --- a/.golangci.yml +++ b/.golangci.yml @@ -1,78 +1,77 @@ # options for analysis running -run: +'run': # default concurrency is a available CPU number - concurrency: 4 + 'concurrency': 4 # timeout for analysis, e.g. 30s, 5m, default is 1m - deadline: 2m + 'deadline': '2m' # which files to skip: they will be analyzed, but issues from them # won't be reported. Default value is empty list, but there is # no need to include all autogenerated files, we confidently recognize # autogenerated files. If it's not please let us know. - skip-files: - - ".*generated.*" - - dnsfilter/rule_to_regexp.go - - util/pprof.go - - ".*_test.go" - - client/.* - - build/.* - - dist/.* - + 'skip-files': + - '.*generated.*' + - 'dnsfilter/rule_to_regexp.go' + - 'util/pprof.go' + - '.*_test.go' + - 'client/.*' + - 'build/.*' + - 'dist/.*' # all available settings of specific linters -linters-settings: - errcheck: +'linters-settings': + 'errcheck': # [deprecated] comma-separated list of pairs of the form pkg:regex # the regex is used to ignore names within pkg. (default "fmt:.*"). # see https://github.com/kisielk/errcheck#the-deprecated-method for details - ignore: fmt:.*,net:SetReadDeadline,net/http:^Write - gocyclo: - min-complexity: 20 - lll: - line-length: 200 + 'ignore': 'fmt:.*,net:SetReadDeadline,net/http:^Write' + 'gocyclo': + 'min-complexity': 20 + 'lll': + 'line-length': 200 -linters: - enable: - - deadcode - - errcheck - - govet - - ineffassign - - staticcheck - - unused - - varcheck - - bodyclose - - depguard - - dupl - - gocyclo - - goimports - - golint - - gosec - - misspell - - stylecheck - - unconvert - disable-all: true - fast: true +'linters': + 'enable': + - 'bodyclose' + - 'deadcode' + - 'depguard' + - 'dupl' + - 'errcheck' + - 'gocyclo' + - 'goimports' + - 'golint' + - 'gosec' + - 'govet' + - 'ineffassign' + - 'misspell' + - 'staticcheck' + - 'stylecheck' + - 'unconvert' + - 'unused' + - 'varcheck' + 'disable-all': true + 'fast': true -issues: +'issues': # List of regexps of issue texts to exclude, empty list by default. # But independently from this option we use default exclude patterns, # it can be disabled by `exclude-use-default: false`. To list all # excluded by default patterns execute `golangci-lint run --help` - exclude: - # structcheck cannot detect usages while they're there - - .parentalServer. is unused - - .safeBrowsingServer. is unused - # errcheck - - Error return value of .s.closeConn. is not checked - - Error return value of ..*.Shutdown. - # goconst - - string .forcesafesearch.google.com. has 3 occurrences - # gosec: Profiling endpoint is automatically exposed on /debug/pprof - - G108 - # gosec: Subprocess launched with function call as argument or cmd arguments - - G204 - # gosec: Potential DoS vulnerability via decompression bomb - - G110 - # gosec: Expect WriteFile permissions to be 0600 or less - - G306 + 'exclude': + # structcheck cannot detect usages while they're there + - '.parentalServer. is unused' + - '.safeBrowsingServer. is unused' + # errcheck + - 'Error return value of .s.closeConn. is not checked' + - 'Error return value of ..*.Shutdown.' + # goconst + - 'string .forcesafesearch.google.com. has 3 occurrences' + # gosec: Profiling endpoint is automatically exposed on /debug/pprof + - 'G108' + # gosec: Subprocess launched with function call as argument or cmd arguments + - 'G204' + # gosec: Potential DoS vulnerability via decompression bomb + - 'G110' + # gosec: Expect WriteFile permissions to be 0600 or less + - 'G306' diff --git a/.goreleaser.yml b/.goreleaser.yml index edb4bd2b..14a6b3d7 100644 --- a/.goreleaser.yml +++ b/.goreleaser.yml @@ -1,106 +1,107 @@ -project_name: AdGuardHome +'project_name': 'AdGuardHome' -env: - - GO111MODULE=on - - GOPROXY=https://goproxy.io +'env': +- 'GO111MODULE=on' +- 'GOPROXY=https://goproxy.io' -before: - hooks: - - go mod download - - go generate ./... +'before': + 'hooks': + - 'go mod download' + - 'go generate ./...' -builds: - - main: ./main.go - ldflags: - - -s -w -X main.version={{.Version}} -X main.channel={{.Env.CHANNEL}} -X main.goarm={{.Env.GOARM}} - env: - - CGO_ENABLED=0 - goos: - - darwin - - linux - - freebsd - - windows - goarch: - - 386 - - amd64 - - arm - - arm64 - - mips - - mipsle - - mips64 - - mips64le - goarm: - - 5 - - 6 - - 7 - gomips: - - softfloat - ignore: - - goos: freebsd - goarch: mips - - goos: freebsd - goarch: mipsle +'builds': +- 'main': './main.go' + 'ldflags': + - '-s -w -X main.version={{.Version}} -X main.channel={{.Env.CHANNEL}} -X main.goarm={{.Env.GOARM}}' + 'env': + - 'CGO_ENABLED=0' + 'goos': + - 'darwin' + - 'linux' + - 'freebsd' + - 'windows' + 'goarch': + - '386' + - 'amd64' + - 'arm' + - 'arm64' + - 'mips' + - 'mipsle' + - 'mips64' + - 'mips64le' + 'goarm': + - '5' + - '6' + - '7' + 'gomips': + - 'softfloat' + 'ignore': + - 'goos': 'freebsd' + 'goarch': 'mips' + - 'goos': 'freebsd' + 'goarch': 'mipsle' -archives: - - # Archive name template. - # Defaults: - # - if format is `tar.gz`, `tar.xz`, `gz` or `zip`: - # - `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }}` - # - if format is `binary`: - # - `{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }}` - name_template: "{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }}" - wrap_in_directory: "AdGuardHome" - format_overrides: - - goos: windows - format: zip - - goos: darwin - format: zip - files: - - LICENSE.txt - - README.md +'archives': +- # Archive name template. + # Defaults: + # - if format is `tar.gz`, `tar.xz`, `gz` or `zip`: + # - `{{ .ProjectName }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }}` + # - if format is `binary`: + # - `{{ .Binary }}_{{ .Version }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }}` + 'name_template': '{{ .ProjectName }}_{{ .Os }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}{{ if .Mips }}_{{ .Mips }}{{ end }}' + 'wrap_in_directory': 'AdGuardHome' + 'format_overrides': + - 'goos': 'windows' + 'format': 'zip' + - 'goos': 'darwin' + 'format': 'zip' + 'files': + - 'LICENSE.txt' + - 'README.md' -snapcrafts: - - name: adguard-home - base: core18 - name_template: '{{ .ProjectName }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}' - summary: Network-wide ads & trackers blocking DNS server - description: | - AdGuard Home is a network-wide software for blocking ads & tracking. After - you set it up, it'll cover ALL your home devices, and you don't need any - client-side software for that. +'snapcrafts': +- 'name': 'adguard-home' + 'base': 'core18' + 'name_template': '{{ .ProjectName }}_{{ .Arch }}{{ if .Arm }}v{{ .Arm }}{{ end }}' + 'summary': 'Network-wide ads & trackers blocking DNS server' + 'description': | + AdGuard Home is a network-wide software for blocking ads & tracking. After + you set it up, it'll cover ALL your home devices, and you don't need any + client-side software for that. - It operates as a DNS server that re-routes tracking domains to a "black hole," - thus preventing your devices from connecting to those servers. It's based - on software we use for our public AdGuard DNS servers -- both share a lot - of common code. - grade: stable - confinement: strict - publish: false - license: GPL-3.0 - extra_files: - - source: scripts/snap/local/adguard-home-web.sh - destination: adguard-home-web.sh - mode: 0755 - - source: scripts/snap/gui/adguard-home-web.desktop - destination: meta/gui/adguard-home-web.desktop - mode: 0644 - - source: scripts/snap/gui/adguard-home-web.png - destination: meta/gui/adguard-home-web.png - mode: 0644 - apps: - adguard-home: - command: AdGuardHome -w $SNAP_DATA --no-check-update - plugs: - # Add the "netrwork-bind" plug to bind to interfaces. - - network-bind - # Add the "netrwork-control" plug to be able to bind to ports below - # 1024 (cap_net_bind_service) and also to bind to a particular - # interface using SO_BINDTODEVICE (cap_net_raw). - - network-control - daemon: simple - adguard-home-web: - command: adguard-home-web.sh - plugs: [ desktop ] + It operates as a DNS server that re-routes tracking domains to a "black hole," + thus preventing your devices from connecting to those servers. It's based + on software we use for our public AdGuard DNS servers -- both share a lot + of common code. + 'grade': 'stable' + 'confinement': 'strict' + 'publish': false + 'license': 'GPL-3.0' + 'extra_files': + - 'source': 'scripts/snap/local/adguard-home-web.sh' + 'destination': 'adguard-home-web.sh' + 'mode': 0755 + - 'source': 'scripts/snap/gui/adguard-home-web.desktop' + 'destination': 'meta/gui/adguard-home-web.desktop' + 'mode': 0644 + - 'source': 'scripts/snap/gui/adguard-home-web.png' + 'destination': 'meta/gui/adguard-home-web.png' + 'mode': 0644 + 'apps': + 'adguard-home': + 'command': 'AdGuardHome -w $SNAP_DATA --no-check-update' + 'plugs': + # Add the "netrwork-bind" plug to bind to interfaces. + - 'network-bind' + # Add the "netrwork-control" plug to be able to bind to ports below + # 1024 (cap_net_bind_service) and also to bind to a particular + # interface using SO_BINDTODEVICE (cap_net_raw). + - 'network-control' + 'daemon': 'simple' + 'adguard-home-web': + 'command': 'adguard-home-web.sh' + 'plugs': + - 'desktop' -checksum: - name_template: 'checksums.txt' +'checksum': + 'name_template': 'checksums.txt' diff --git a/HACKING.md b/HACKING.md index 8df23efd..fbd56cc4 100644 --- a/HACKING.md +++ b/HACKING.md @@ -1,9 +1,11 @@ # AdGuardHome Developer Guidelines -As of **2020-11-12**, this document is still a work-in-progress. Some of the +As of **2020-11-20**, this document is still a work-in-progress. Some of the rules aren't enforced, and others might change. Still, this is a good place to find out about how we **want** our code to look like. +The rules are mostly sorted in the alphabetical order. + ## Git * Follow the commit message header format: @@ -13,11 +15,14 @@ find out about how we **want** our code to look like. ``` Where `pkg` is the package where most changes took place. If there are - several such packages, just write `all`. + several such packages, or the change is top-level only, write `all`. - * Keep your commit messages to be no wider than eighty (**80**) columns. + * Keep your commit messages, including headers, to eighty (**80**) columns. - * Only use lowercase letters in your commit message headers. + * Only use lowercase letters in your commit message headers. The rest of the + message should follow the plain text conventions below. + + The only exception are direct mentions of identifiers from the source code. ## Go @@ -98,8 +103,20 @@ find out about how we **want** our code to look like. [constant errors]: https://dave.cheney.net/2016/04/07/constant-errors [Linus said]: https://www.kernel.org/doc/html/v4.17/process/coding-style.html#indentation +## Markdown + + * **TODO(a.garipov):** Define our Markdown conventions. + ## Text, Including Comments + * End sentences with appropriate punctuation. + + * Headers should be written with all initial letters capitalized, except for + references to variable names that start with a lowercase letter. + + * Start sentences with a capital letter, unless the first word is a reference + to a variable name that starts with a lowercase letter. + * Text should wrap at eighty (**80**) columns to be more readable, to use a common standard, and to allow editing or diffing side-by-side without wrapping. @@ -126,17 +143,17 @@ find out about how we **want** our code to look like. // TODO(usr1, usr2): Fix the frobulation issue. ``` -## Markdown - - * **TODO(a.garipov):** Define our Markdown conventions. - ## YAML + * **TODO(a.garipov):** Define naming conventions for schema names in our + OpenAPI YAML file. And just generally OpenAPI conventions. + * **TODO(a.garipov):** Find a YAML formatter or write our own. * All strings, including keys, must be quoted. Reason: the [NO-rway Law]. - * Indent with two (**2**) spaces. + * Indent with two (**2**) spaces. YAML documents can get pretty + deeply-nested. * No extra indentation in multiline arrays: @@ -147,7 +164,10 @@ find out about how we **want** our code to look like. - 'value-3' ``` - * Prefer single quotes for string to prevent accidental escaping, unless - escaping is required. + * Prefer single quotes for strings to prevent accidental escaping, unless + escaping is required or there are single quotes inside the string (e.g. for + *GitHub Actions*). + + * Use `>` for multiline strings, unless you need to keep the line breaks. [NO-rway Law]: https://news.ycombinator.com/item?id=17359376 diff --git a/openapi/openapi.yaml b/openapi/openapi.yaml index d42ee24c..05552218 100644 --- a/openapi/openapi.yaml +++ b/openapi/openapi.yaml @@ -1,2021 +1,2052 @@ -openapi: 3.0.3 -info: - title: AdGuard Home - description: AdGuard Home REST API. Admin web interface is built on top of this REST API. - version: "0.104" - contact: - name: "AdGuard Home" - url: "https://github.com/AdguardTeam/AdGuardHome" +'openapi': '3.0.3' +'info': + 'title': 'AdGuard Home' + 'description': > + AdGuard Home REST API. Our admin web interface is built on top of this REST + API. + 'version': '0.104' + 'contact': + 'name': 'AdGuard Home' + 'url': 'https://github.com/AdguardTeam/AdGuardHome' -servers: - - url: /control +'servers': +- 'url': '/control' -tags: - - name: clients - description: Clients list operations - - name: dhcp - description: Built-in DHCP server controls - - name: filtering - description: Rule-based filtering - - name: global - description: AdGuard Home server general settings and controls - - name: i18n - description: Application localization - - name: install - description: First-time install configuration handlers - - name: log - description: AdGuard Home query log - - name: parental - description: Blocking adult and explicit materials - - name: safebrowsing - description: Blocking malware/phishing sites - - name: safesearch - description: Enforce family-friendly results in search engines - - name: stats - description: AdGuard Home statistics - - name: tls - description: AdGuard Home HTTPS/DOH/DOT settings - - name: mobileconfig - description: Apple .mobileconfig +'tags': +- 'name': 'clients' + 'description': 'Clients list operations' +- 'name': 'dhcp' + 'description': 'Built-in DHCP server controls' +- 'name': 'filtering' + 'description': 'Rule-based filtering' +- 'name': 'global' + 'description': 'AdGuard Home server general settings and controls' +- 'name': 'i18n' + 'description': 'Application localization' +- 'name': 'install' + 'description': 'First-time install configuration handlers' +- 'name': 'log' + 'description': 'AdGuard Home query log' +- 'name': 'mobileconfig' + 'description': 'Apple .mobileconfig' +- 'name': 'parental' + 'description': 'Blocking adult and explicit materials' +- 'name': 'safebrowsing' + 'description': 'Blocking malware/phishing sites' +- 'name': 'safesearch' + 'description': 'Enforce family-friendly results in search engines' +- 'name': 'stats' + 'description': 'AdGuard Home statistics' +- 'name': 'tls' + 'description': 'AdGuard Home HTTPS/DOH/DOT settings' -paths: - /status: - get: - tags: - - global - operationId: status - summary: Get DNS server current status and general settings - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ServerStatus" - /dns_info: - get: - tags: - - global - operationId: dnsInfo - summary: Get general DNS parameters - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/DNSConfig" - /dns_config: - post: - tags: - - global - operationId: dnsConfig - summary: Set general DNS parameters - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/DNSConfig" - responses: - "200": - description: OK - /test_upstream_dns: - post: - tags: - - global - operationId: testUpstreamDNS - summary: Test upstream configuration - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/UpstreamsConfig" - description: Upstream configuration to be tested - responses: - "200": - description: Status of testing each requested server, with "OK" meaning that - server works, any other text means an error. - content: - application/json: - examples: - response: - value: - 1.1.1.1: OK - 1.0.0.1: OK - 8.8.8.8: OK - 8.8.4.4: OK - 192.168.1.104:53535: Couldn't communicate with DNS server - /version.json: - post: - tags: - - global - operationId: getVersionJson - summary: Gets information about the latest available version of AdGuard - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/GetVersionRequest" - required: true - responses: - "200": - description: Version info. If response message is empty, UI does not show a - version update message. - content: - application/json: - schema: - $ref: "#/components/schemas/VersionInfo" - "500": - description: Cannot write answer - "502": - description: Cannot retrieve the version.json file contents - /update: - post: - tags: - - global - operationId: beginUpdate - summary: Begin auto-upgrade procedure - responses: - "200": - description: OK - "500": - description: Failed - /querylog: - get: - tags: - - log - operationId: queryLog - summary: Get DNS server query log. - parameters: - - name: older_than - in: query - description: Filter by older than - schema: - type: string - - name: offset - in: query - description: - Specify the ranking number of the first item on the page. - Even though it is possible to use "offset" and "older_than", - we recommend choosing one of them and sticking to it. - schema: - type: integer - - name: limit - in: query - description: Limit the number of records to be returned - schema: - type: integer - - name: search - in: query - description: Filter by domain name or client IP - schema: - type: string - - name: response_status - in: query - description: Filter by response status - schema: - type: string - enum: - - all - - filtered - - blocked - - blocked_safebrowsing - - blocked_parental - - whitelisted - - rewritten - - safe_search - - processed - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/QueryLog" - /querylog_info: - get: - tags: - - log - operationId: queryLogInfo - summary: Get query log parameters - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/QueryLogConfig" - /querylog_config: - post: - tags: - - log - operationId: queryLogConfig - summary: Set query log parameters - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/QueryLogConfig" - responses: - "200": - description: OK - /querylog_clear: - post: - tags: - - log - operationId: querylogClear - summary: Clear query log - responses: - "200": - description: OK - /stats: - get: - tags: - - stats - operationId: stats - summary: Get DNS server statistics - responses: - "200": - description: Returns statistics data - content: - application/json: - schema: - $ref: "#/components/schemas/Stats" - /stats_reset: - post: - tags: - - stats - operationId: statsReset - summary: Reset all statistics to zeroes - responses: - "200": - description: OK - /stats_info: - get: - tags: - - stats - operationId: statsInfo - summary: Get statistics parameters - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/StatsConfig" - /stats_config: - post: - tags: - - stats - operationId: statsConfig - summary: Set statistics parameters - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/StatsConfig" - responses: - "200": - description: OK - /tls/status: - get: - tags: - - tls - operationId: tlsStatus - summary: Returns TLS configuration and its status - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/TlsConfig" - /tls/configure: - post: - tags: - - tls - operationId: tlsConfigure - summary: Updates current TLS configuration - requestBody: - $ref: "#/components/requestBodies/TlsConfig" - responses: - "200": - description: TLS configuration and its status - content: - application/json: - schema: - $ref: "#/components/schemas/TlsConfig" - "400": - description: Invalid configuration or unavailable port - "500": - description: Error occurred while applying configuration - /tls/validate: - post: - tags: - - tls - operationId: tlsValidate - summary: Checks if the current TLS configuration is valid - requestBody: - $ref: "#/components/requestBodies/TlsConfig" - responses: - "200": - description: TLS configuration and its status - content: - application/json: - schema: - $ref: "#/components/schemas/TlsConfig" - "400": - description: Invalid configuration or unavailable port - /dhcp/status: - get: - tags: - - dhcp - operationId: dhcpStatus - summary: Gets the current DHCP settings and status - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/DhcpStatus" - "501": - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - description: Not implemented (for example, on Windows). - /dhcp/set_config: - post: - tags: - - dhcp - operationId: dhcpSetConfig - summary: Updates the current DHCP server configuration - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/DhcpConfig" - responses: - "200": - description: OK - "501": - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - description: Not implemented (for example, on Windows). - /dhcp/find_active_dhcp: - post: - tags: - - dhcp - operationId: checkActiveDhcp - summary: Searches for an active DHCP server on the network - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/DhcpSearchResult" - "501": - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - description: Not implemented (for example, on Windows). - /dhcp/add_static_lease: - post: - tags: - - dhcp - operationId: dhcpAddStaticLease - summary: Adds a static lease - requestBody: - $ref: "#/components/requestBodies/DhcpStaticLease" - responses: - "200": - description: OK - "501": - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - description: Not implemented (for example, on Windows). - /dhcp/remove_static_lease: - post: - tags: - - dhcp - operationId: dhcpRemoveStaticLease - summary: Removes a static lease - requestBody: - $ref: "#/components/requestBodies/DhcpStaticLease" - responses: - "200": - description: OK - "501": - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - description: Not implemented (for example, on Windows). - /dhcp/reset: - post: - tags: - - dhcp - operationId: dhcpReset - summary: Reset DHCP configuration - responses: - "200": - description: OK - "501": - content: - application/json: - schema: - $ref: "#/components/schemas/Error" - description: Not implemented (for example, on Windows). - /filtering/status: - get: - tags: - - filtering - operationId: filteringStatus - summary: Get filtering parameters - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/FilterStatus" - /filtering/config: - post: - tags: - - filtering - operationId: filteringConfig - summary: Set filtering parameters - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/FilterConfig" - required: true - responses: - "200": - description: OK - /filtering/add_url: - post: - tags: - - filtering - operationId: filteringAddURL - summary: Add filter URL or an absolute file path - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/AddUrlRequest" - required: true - responses: - "200": - description: OK - /filtering/remove_url: - post: - tags: - - filtering - operationId: filteringRemoveURL - summary: Remove filter URL - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/RemoveUrlRequest" - required: true - responses: - "200": - description: OK - /filtering/set_url: - post: - tags: - - filtering - operationId: filteringSetURL - summary: Set URL parameters - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/FilterSetUrl" - responses: - "200": - description: OK - /filtering/refresh: - post: - tags: - - filtering - operationId: filteringRefresh - summary: > - Reload filtering rules from URLs +'paths': + '/status': + 'get': + 'tags': + - 'global' + 'operationId': 'status' + 'summary': 'Get DNS server current status and general settings' + 'responses': + '200': + 'description': 'OK' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/ServerStatus' + '/dns_info': + 'get': + 'tags': + - 'global' + 'operationId': 'dnsInfo' + 'summary': 'Get general DNS parameters' + 'responses': + '200': + 'description': 'OK' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/DNSConfig' + '/dns_config': + 'post': + 'tags': + - 'global' + 'operationId': 'dnsConfig' + 'summary': 'Set general DNS parameters' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/DNSConfig' + 'responses': + '200': + 'description': 'OK' + '/test_upstream_dns': + 'post': + 'tags': + - 'global' + 'operationId': 'testUpstreamDNS' + 'summary': 'Test upstream configuration' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/UpstreamsConfig' + 'description': 'Upstream configuration to be tested' + 'responses': + '200': + 'description': > + Status of testing each requested server, with "OK" meaning that + server works, any other text means an error. + 'content': + 'application/json': + 'examples': + 'response': + 'value': + '1.1.1.1': 'OK' + '1.0.0.1': 'OK' + '8.8.8.8': 'OK' + '8.8.4.4': 'OK' + '192.168.1.104:53535': > + Couldn't communicate with DNS server + '/version.json': + 'post': + 'tags': + - 'global' + 'operationId': 'getVersionJson' + 'summary': > + Gets information about the latest available version of AdGuard + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/GetVersionRequest' + 'required': true + 'responses': + '200': + 'description': > + Version info. If response message is empty, UI does not show + a version update message. + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/VersionInfo' + '500': + 'description': 'Cannot write answer' + '502': + 'description': 'Cannot retrieve the version.json file contents' + '/update': + 'post': + 'tags': + - 'global' + 'operationId': 'beginUpdate' + 'summary': 'Begin auto-upgrade procedure' + 'responses': + '200': + 'description': 'OK.' + '500': + 'description': 'Failed' + '/querylog': + 'get': + 'tags': + - 'log' + 'operationId': 'queryLog' + 'summary': 'Get DNS server query log.' + 'parameters': + - 'name': 'older_than' + 'in': 'query' + 'description': 'Filter by older than' + 'schema': + 'type': 'string' + - 'name': 'offset' + 'in': 'query' + 'description': > + Specify the ranking number of the first item on the page. Even + though it is possible to use "offset" and "older_than", we recommend + choosing one of them and sticking to it. + 'schema': + 'type': 'integer' + - 'name': 'limit' + 'in': 'query' + 'description': 'Limit the number of records to be returned' + 'schema': + 'type': 'integer' + - 'name': 'search' + 'in': 'query' + 'description': 'Filter by domain name or client IP' + 'schema': + 'type': 'string' + - 'name': 'response_status' + 'in': 'query' + 'description': 'Filter by response status' + 'schema': + 'type': 'string' + 'enum': + - 'all' + - 'filtered' + - 'blocked' + - 'blocked_safebrowsing' + - 'blocked_parental' + - 'whitelisted' + - 'rewritten' + - 'safe_search' + - 'processed' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/QueryLog' + '/querylog_info': + 'get': + 'tags': + - 'log' + 'operationId': 'queryLogInfo' + 'summary': 'Get query log parameters' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/QueryLogConfig' + '/querylog_config': + 'post': + 'tags': + - 'log' + 'operationId': 'queryLogConfig' + 'summary': 'Set query log parameters' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/QueryLogConfig' + 'responses': + '200': + 'description': 'OK.' + '/querylog_clear': + 'post': + 'tags': + - 'log' + 'operationId': 'querylogClear' + 'summary': 'Clear query log' + 'responses': + '200': + 'description': 'OK.' + '/stats': + 'get': + 'tags': + - 'stats' + 'operationId': 'stats' + 'summary': 'Get DNS server statistics' + 'responses': + '200': + 'description': 'Returns statistics data' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Stats' + '/stats_reset': + 'post': + 'tags': + - 'stats' + 'operationId': 'statsReset' + 'summary': 'Reset all statistics to zeroes' + 'responses': + '200': + 'description': 'OK.' + '/stats_info': + 'get': + 'tags': + - 'stats' + 'operationId': 'statsInfo' + 'summary': 'Get statistics parameters' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/StatsConfig' + '/stats_config': + 'post': + 'tags': + - 'stats' + 'operationId': 'statsConfig' + 'summary': 'Set statistics parameters' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/StatsConfig' + 'responses': + '200': + 'description': 'OK.' + '/tls/status': + 'get': + 'tags': + - 'tls' + 'operationId': 'tlsStatus' + 'summary': 'Returns TLS configuration and its status' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/TlsConfig' + '/tls/configure': + 'post': + 'tags': + - 'tls' + 'operationId': 'tlsConfigure' + 'summary': 'Updates current TLS configuration' + 'requestBody': + '$ref': '#/components/requestBodies/TlsConfig' + 'responses': + '200': + 'description': 'TLS configuration and its status' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/TlsConfig' + '400': + 'description': 'Invalid configuration or unavailable port' + '500': + 'description': 'Error occurred while applying configuration' + '/tls/validate': + 'post': + 'tags': + - 'tls' + 'operationId': 'tlsValidate' + 'summary': 'Checks if the current TLS configuration is valid' + 'requestBody': + '$ref': '#/components/requestBodies/TlsConfig' + 'responses': + '200': + 'description': 'TLS configuration and its status' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/TlsConfig' + '400': + 'description': 'Invalid configuration or unavailable port' + '/dhcp/status': + 'get': + 'tags': + - 'dhcp' + 'operationId': 'dhcpStatus' + 'summary': 'Gets the current DHCP settings and status' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/DhcpStatus' + '501': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Error' + 'description': 'Not implemented (for example, on Windows).' + '/dhcp/set_config': + 'post': + 'tags': + - 'dhcp' + 'operationId': 'dhcpSetConfig' + 'summary': 'Updates the current DHCP server configuration' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/DhcpConfig' + 'responses': + '200': + 'description': 'OK.' + '501': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Error' + 'description': 'Not implemented (for example, on Windows).' + '/dhcp/find_active_dhcp': + 'post': + 'tags': + - 'dhcp' + 'operationId': 'checkActiveDhcp' + 'summary': 'Searches for an active DHCP server on the network' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/DhcpSearchResult' + '501': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Error' + 'description': 'Not implemented (for example, on Windows).' + '/dhcp/add_static_lease': + 'post': + 'tags': + - 'dhcp' + 'operationId': 'dhcpAddStaticLease' + 'summary': 'Adds a static lease' + 'requestBody': + '$ref': '#/components/requestBodies/DhcpStaticLease' + 'responses': + '200': + 'description': 'OK.' + '501': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Error' + 'description': 'Not implemented (for example, on Windows).' + '/dhcp/remove_static_lease': + 'post': + 'tags': + - 'dhcp' + 'operationId': 'dhcpRemoveStaticLease' + 'summary': 'Removes a static lease' + 'requestBody': + '$ref': '#/components/requestBodies/DhcpStaticLease' + 'responses': + '200': + 'description': 'OK.' + '501': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Error' + 'description': 'Not implemented (for example, on Windows).' + '/dhcp/reset': + 'post': + 'tags': + - 'dhcp' + 'operationId': 'dhcpReset' + 'summary': 'Reset DHCP configuration' + 'responses': + '200': + 'description': 'OK.' + '501': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Error' + 'description': 'Not implemented (for example, on Windows).' + '/filtering/status': + 'get': + 'tags': + - 'filtering' + 'operationId': 'filteringStatus' + 'summary': 'Get filtering parameters' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/FilterStatus' + '/filtering/config': + 'post': + 'tags': + - 'filtering' + 'operationId': 'filteringConfig' + 'summary': 'Set filtering parameters' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/FilterConfig' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/filtering/add_url': + 'post': + 'tags': + - 'filtering' + 'operationId': 'filteringAddURL' + 'summary': 'Add filter URL or an absolute file path' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/AddUrlRequest' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/filtering/remove_url': + 'post': + 'tags': + - 'filtering' + 'operationId': 'filteringRemoveURL' + 'summary': 'Remove filter URL' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/RemoveUrlRequest' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/filtering/set_url': + 'post': + 'tags': + - 'filtering' + 'operationId': 'filteringSetURL' + 'summary': 'Set URL parameters' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/FilterSetUrl' + 'responses': + '200': + 'description': 'OK.' + '/filtering/refresh': + 'post': + 'tags': + - 'filtering' + 'operationId': 'filteringRefresh' + 'summary': > + Reload filtering rules from URLs. This might be needed if new URL was + just added and you dont want to wait for automatic refresh to kick in. + This API request is ratelimited, so you can call it freely as often as + you like, it wont create unneccessary burden on servers that host the + URL. This should work as intended, a `force` parameter is offered as + last-resort attempt to make filter lists fresh. If you ever find + yourself using `force` to make something work that otherwise wont, this + is a bug and report it accordingly. + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/FilterRefreshRequest' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/FilterRefreshResponse' + '/filtering/set_rules': + 'post': + 'tags': + - 'filtering' + 'operationId': 'filteringSetRules' + 'summary': 'Set user-defined filter rules' + 'requestBody': + 'content': + 'text/plain': + 'schema': + 'type': 'string' + 'example': '@@||yandex.ru^|' + 'description': 'All filtering rules, one line per rule' + 'responses': + '200': + 'description': 'OK.' + '/filtering/check_host': + 'get': + 'tags': + - 'filtering' + 'operationId': 'filteringCheckHost' + 'summary': 'Check if host name is filtered' + 'parameters': + - 'name': 'name' + 'in': 'query' + 'description': 'Filter by host name' + 'schema': + 'type': 'string' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/FilterCheckHostResponse' + '/safebrowsing/enable': + 'post': + 'tags': + - 'safebrowsing' + 'operationId': 'safebrowsingEnable' + 'summary': 'Enable safebrowsing' + 'responses': + '200': + 'description': 'OK.' + '/safebrowsing/disable': + 'post': + 'tags': + - 'safebrowsing' + 'operationId': 'safebrowsingDisable' + 'summary': 'Disable safebrowsing' + 'responses': + '200': + 'description': 'OK.' + '/safebrowsing/status': + 'get': + 'tags': + - 'safebrowsing' + 'operationId': 'safebrowsingStatus' + 'summary': 'Get safebrowsing status' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'examples': + 'response': + 'value': + 'enabled': false + '/parental/enable': + 'post': + 'tags': + - 'parental' + 'operationId': 'parentalEnable' + 'summary': 'Enable parental filtering' + 'requestBody': + 'content': + 'text/plain': + 'schema': + 'type': 'string' + 'enum': + - 'EARLY_CHILDHOOD' + - 'YOUNG' + - 'TEEN' + - 'MATURE' + 'example': 'sensitivity=TEEN' + 'description': | + Age sensitivity for parental filtering, + EARLY_CHILDHOOD is 3 + YOUNG is 10 + TEEN is 13 + MATURE is 17 + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/parental/disable': + 'post': + 'tags': + - 'parental' + 'operationId': 'parentalDisable' + 'summary': 'Disable parental filtering' + 'responses': + '200': + 'description': 'OK.' + '/parental/status': + 'get': + 'tags': + - 'parental' + 'operationId': 'parentalStatus' + 'summary': 'Get parental filtering status' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'examples': + 'response': + 'value': + 'enabled': true + 'sensitivity': 13 + '/safesearch/enable': + 'post': + 'tags': + - 'safesearch' + 'operationId': 'safesearchEnable' + 'summary': 'Enable safesearch' + 'responses': + '200': + 'description': 'OK.' + '/safesearch/disable': + 'post': + 'tags': + - 'safesearch' + 'operationId': 'safesearchDisable' + 'summary': 'Disable safesearch' + 'responses': + '200': + 'description': 'OK.' + '/safesearch/status': + 'get': + 'tags': + - 'safesearch' + 'operationId': 'safesearchStatus' + 'summary': 'Get safesearch status' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'examples': + 'response': + 'value': + 'enabled': false + '/clients': + 'get': + 'tags': + - 'clients' + 'operationId': 'clientsStatus' + 'summary': 'Get information about configured clients' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Clients' + '/clients/add': + 'post': + 'tags': + - 'clients' + 'operationId': 'clientsAdd' + 'summary': 'Add a new client' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Client' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/clients/delete': + 'post': + 'tags': + - 'clients' + 'operationId': 'clientsDelete' + 'summary': 'Remove a client' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/ClientDelete' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/clients/update': + 'post': + 'tags': + - 'clients' + 'operationId': 'clientsUpdate' + 'summary': 'Update client information' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/ClientUpdate' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/clients/find': + 'get': + 'tags': + - 'clients' + 'operationId': 'clientsFind' + 'summary': 'Get information about selected clients by their IP address' + 'parameters': + - 'name': 'ip0' + 'in': 'query' + 'description': 'Filter by IP address' + 'schema': + 'type': 'string' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/ClientsFindResponse' + '/blocked_services/list': + 'get': + 'tags': + - 'blocked_services' + 'operationId': 'blockedServicesList' + 'summary': 'Get blocked services list' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/BlockedServicesArray' + '/blocked_services/set': + 'post': + 'tags': + - 'blocked_services' + 'operationId': 'blockedServicesSet' + 'summary': 'Set blocked services list' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/BlockedServicesArray' + 'responses': + '200': + 'description': 'OK.' + '/rewrite/list': + 'get': + 'tags': + - 'rewrite' + 'operationId': 'rewriteList' + 'summary': 'Get list of Rewrite rules' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/RewriteList' + '/rewrite/add': + 'post': + 'tags': + - 'rewrite' + 'operationId': 'rewriteAdd' + 'summary': 'Add a new Rewrite rule' + 'requestBody': + '$ref': '#/components/requestBodies/RewriteEntry' + 'responses': + '200': + 'description': 'OK.' + '/rewrite/delete': + 'post': + 'tags': + - 'rewrite' + 'operationId': 'rewriteDelete' + 'summary': 'Remove a Rewrite rule' + 'requestBody': + '$ref': '#/components/requestBodies/RewriteEntry' + 'responses': + '200': + 'description': 'OK.' + '/i18n/change_language': + 'post': + 'tags': + - 'i18n' + 'operationId': 'changeLanguage' + 'summary': > + Change current language. Argument must be an ISO 639-1 two-letter code. + 'requestBody': + 'content': + 'text/plain': + 'schema': + 'type': 'string' + 'example': 'en' + 'description': > + New language. It must be known to the server and must be an ISO 639-1 + two-letter code. + 'responses': + '200': + 'description': 'OK.' + '/i18n/current_language': + 'get': + 'tags': + - 'i18n' + 'operationId': 'currentLanguage' + 'summary': > + Get currently set language. Result is ISO 639-1 two-letter code. Empty + result means default language. + 'responses': + '200': + 'description': 'OK.' + 'content': + 'text/plain': + 'examples': + 'response': + 'value': 'en' + '/install/get_addresses': + 'get': + 'tags': + - 'install' + 'operationId': 'installGetAddresses' + 'summary': 'Gets the network interfaces information.' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/AddressesInfo' + '/install/check_config': + 'post': + 'tags': + - 'install' + 'operationId': 'installCheckConfig' + 'summary': 'Checks configuration' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/CheckConfigRequest' + 'description': 'Configuration to be checked' + 'required': true + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/CheckConfigResponse' + '400': + 'description': > + Failed to parse JSON or cannot listen on the specified address. + '/install/configure': + 'post': + 'tags': + - 'install' + 'operationId': 'installConfigure' + 'summary': 'Applies the initial configuration.' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/InitialConfiguration' + 'description': 'Initial configuration JSON' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '400': + 'description': > + Failed to parse initial configuration or cannot listen to the + specified addresses. + '500': + 'description': 'Cannot start the DNS server' + '/login': + 'post': + 'tags': + - 'global' + 'operationId': 'login' + 'summary': 'Perform administrator log-in' + 'requestBody': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/Login' + 'required': true + 'responses': + '200': + 'description': 'OK.' + '/logout': + 'get': + 'tags': + - 'global' + 'operationId': 'logout' + 'summary': 'Perform administrator log-out' + 'responses': + '302': + 'description': 'OK.' + '/profile': + 'get': + 'tags': + - 'global' + 'operationId': 'getProfile' + 'summary': '' + 'responses': + '200': + 'description': 'OK.' + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/ProfileInfo' + '/apple/doh.mobileconfig': + 'get': + 'tags': + - 'mobileconfig' + - 'global' + 'operationId': 'mobileConfigDoH' + 'summary': 'Get DNS over HTTPS .mobileconfig' + 'responses': + '200': + 'description': 'DNS over HTTPS plist file' + '/apple/dot.mobileconfig': + 'get': + 'tags': + - 'mobileconfig' + - 'global' + 'operationId': 'mobileConfigDoT' + 'summary': 'Get TLS over TLS .mobileconfig' + 'responses': + '200': + 'description': 'DNS over TLS plist file' - This might be needed if new URL was just added and you dont want to wait for automatic refresh to kick in. +'components': + 'requestBodies': + 'TlsConfig': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/TlsConfig' + 'description': 'TLS configuration JSON' + 'required': true + 'DhcpStaticLease': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/DhcpStaticLease' + 'required': true + 'RewriteEntry': + 'content': + 'application/json': + 'schema': + '$ref': '#/components/schemas/RewriteEntry' + 'required': true + 'schemas': + 'ServerStatus': + 'type': 'object' + 'description': 'AdGuard Home server status and configuration' + 'required': + - 'dns_address' + - 'dns_port' + - 'protection_enabled' + - 'querylog_enabled' + - 'running' + - 'bootstrap_dns' + - 'upstream_dns' + - 'version' + - 'language' + 'properties': + 'dns_address': + 'type': 'string' + 'example': '127.0.0.1' + 'dns_port': + 'type': 'integer' + 'format': 'int32' + 'example': 53 + 'minimum': 1 + 'maximum': 65535 + 'protection_enabled': + 'type': 'boolean' + 'dhcp_available': + 'type': 'boolean' + 'querylog_enabled': + 'type': 'boolean' + 'running': + 'type': 'boolean' + 'version': + 'type': 'string' + 'example': '0.1' + 'language': + 'type': 'string' + 'example': 'en' + 'DNSConfig': + 'type': 'object' + 'description': 'Query log configuration' + 'properties': + 'bootstrap_dns': + 'type': 'array' + 'description': > + Bootstrap servers, port is optional after colon. Empty value will + reset it to default values. + 'items': + 'type': 'string' + 'example': + - '8.8.8.8:53' + - '1.1.1.1:53' + 'upstream_dns': + 'type': 'array' + 'description': > + Upstream servers, port is optional after colon. Empty value will + reset it to default values. + 'items': + 'type': 'string' + 'example': + - 'tls://1.1.1.1' + - 'tls://1.0.0.1' + 'upstream_dns_file': + 'type': 'string' + 'protection_enabled': + 'type': 'boolean' + 'dhcp_available': + 'type': 'boolean' + 'ratelimit': + 'type': 'integer' + 'blocking_mode': + 'type': 'string' + 'enum': + - 'default' + - 'refused' + - 'nxdomain' + - 'null_ip' + - 'custom_ip' + 'blocking_ipv4': + 'type': 'string' + 'blocking_ipv6': + 'type': 'string' + 'edns_cs_enabled': + 'type': 'boolean' + 'dnssec_enabled': + 'type': 'boolean' + 'cache_size': + 'type': 'integer' + 'cache_ttl_min': + 'type': 'integer' + 'cache_ttl_max': + 'type': 'integer' + 'upstream_mode': + 'enum': + - '' + - 'parallel' + - 'fastest_addr' + 'UpstreamsConfig': + 'type': 'object' + 'description': 'Upstreams configuration' + 'required': + - 'bootstrap_dns' + - 'upstream_dns' + 'properties': + 'bootstrap_dns': + 'type': 'array' + 'description': > + Bootstrap servers, port is optional after colon. Empty value will + reset it to default values. + 'items': + 'type': 'string' + 'example': + - '8.8.8.8:53' + - '1.1.1.1:53' + 'upstream_dns': + 'type': 'array' + 'description': > + Upstream servers, port is optional after colon. Empty value will + reset it to default values. + 'items': + 'type': 'string' + 'example': + - 'tls://1.1.1.1' + - 'tls://1.0.0.1' + 'Filter': + 'type': 'object' + 'description': 'Filter subscription info' + 'required': + - 'enabled' + - 'id' + - 'lastUpdated' + - 'name' + - 'rulesCount' + - 'url' + 'properties': + 'enabled': + 'type': 'boolean' + 'id': + 'type': 'integer' + 'example': 1234 + 'lastUpdated': + 'type': 'string' + 'format': 'date-time' + 'example': '2018-10-30T12:18:57+03:00' + 'name': + 'type': 'string' + 'example': 'AdGuard Simplified Domain Names filter' + 'rulesCount': + 'type': 'integer' + 'example': 5912 + 'url': + 'type': 'string' + 'example': > + https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt + 'FilterStatus': + 'type': 'object' + 'description': 'Filtering settings' + 'properties': + 'enabled': + 'type': 'boolean' + 'interval': + 'type': 'integer' + 'filters': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/Filter' + 'user_rules': + 'type': 'array' + 'items': + 'type': 'string' + 'FilterConfig': + 'type': 'object' + 'description': 'Filtering settings' + 'properties': + 'enabled': + 'type': 'boolean' + 'interval': + 'type': 'integer' + 'FilterSetUrl': + 'type': 'object' + 'description': 'Filtering URL settings' + 'properties': + 'data': + 'properties': + 'enabled': + 'type': 'boolean' + 'name': + 'type': 'string' + 'url': + 'type': 'string' + 'type': 'object' + 'url': + 'type': 'string' + 'whitelist': + 'type': 'boolean' + 'FilterRefreshRequest': + 'type': 'object' + 'description': 'Refresh Filters request data' + 'properties': + 'whitelist': + 'type': 'boolean' + 'FilterCheckHostResponse': + 'type': 'object' + 'description': 'Check Host Result' + 'properties': + 'reason': + 'type': 'string' + 'description': 'DNS filter status' + 'enum': + - 'NotFilteredNotFound' + - 'NotFilteredWhiteList' + - 'NotFilteredError' + - 'FilteredBlackList' + - 'FilteredSafeBrowsing' + - 'FilteredParental' + - 'FilteredInvalid' + - 'FilteredSafeSearch' + - 'FilteredBlockedService' + - 'ReasonRewrite' + 'filter_id': + 'type': 'integer' + 'rule': + 'type': 'string' + 'example': '||example.org^' + 'description': 'Filtering rule applied to the request (if any)' + 'service_name': + 'type': 'string' + 'description': 'Set if reason=FilteredBlockedService' + 'cname': + 'type': 'string' + 'description': 'Set if reason=ReasonRewrite' + 'ip_addrs': + 'type': 'array' + 'items': + 'type': 'string' + 'description': 'Set if reason=ReasonRewrite' + 'FilterRefreshResponse': + 'type': 'object' + 'description': '/filtering/refresh response data' + 'properties': + 'updated': + 'type': 'integer' + 'GetVersionRequest': + 'type': 'object' + 'description': '/version.json request data' + 'properties': + 'recheck_now': + 'description': > + If false, server will check for a new version data only once in + several hours. + 'type': 'boolean' + 'VersionInfo': + 'type': 'object' + 'description': > + Information about the latest available version of AdGuard Home. + 'properties': + 'new_version': + 'type': 'string' + 'example': 'v0.9' + 'announcement': + 'type': 'string' + 'example': 'AdGuard Home v0.9 is now available!' + 'announcement_url': + 'type': 'string' + 'example': > + https://github.com/AdguardTeam/AdGuardHome/releases/tag/v0.9 + 'can_autoupdate': + 'type': 'boolean' + 'Stats': + 'type': 'object' + 'description': 'Server statistics data' + 'properties': + 'time_units': + 'type': 'string' + 'description': 'Time units (hours | days)' + 'example': 'hours' + 'num_dns_queries': + 'type': 'integer' + 'description': 'Total number of DNS queries' + 'example': 123 + 'num_blocked_filtering': + 'type': 'integer' + 'description': 'Number of requests blocked by filtering rules' + 'example': 50 + 'num_replaced_safebrowsing': + 'type': 'integer' + 'description': 'Number of requests blocked by safebrowsing module' + 'example': 5 + 'num_replaced_safesearch': + 'type': 'integer' + 'description': 'Number of requests blocked by safesearch module' + 'example': 5 + 'num_replaced_parental': + 'type': 'integer' + 'description': 'Number of blocked adult websites' + 'example': 15 + 'avg_processing_time': + 'type': 'number' + 'format': 'float' + 'description': 'Average time in milliseconds on processing a DNS' + 'example': 0.34 + 'top_queried_domains': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/TopArrayEntry' + 'top_clients': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/TopArrayEntry' + 'top_blocked_domains': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/TopArrayEntry' + 'dns_queries': + 'type': 'array' + 'items': + 'type': 'integer' + 'blocked_filtering': + 'type': 'array' + 'items': + 'type': 'integer' + 'replaced_safebrowsing': + 'type': 'array' + 'items': + 'type': 'integer' + 'replaced_parental': + 'type': 'array' + 'items': + 'type': 'integer' + 'TopArrayEntry': + 'type': 'object' + 'description': > + Represent the number of hits per key (domain or client IP). + 'properties': + 'domain_or_ip': + 'type': 'integer' + 'StatsConfig': + 'type': 'object' + 'description': 'Statistics configuration' + 'properties': + 'interval': + 'type': 'integer' + 'description': 'Time period to keep data (1 | 7 | 30 | 90)' + 'DhcpConfig': + 'type': 'object' + 'properties': + 'enabled': + 'type': 'boolean' + 'interface_name': + 'type': 'string' + 'v4': + '$ref': '#/components/schemas/DhcpConfigV4' + 'v6': + '$ref': '#/components/schemas/DhcpConfigV6' + 'DhcpConfigV4': + 'type': 'object' + 'properties': + 'gateway_ip': + 'type': 'string' + 'example': '192.168.1.1' + 'subnet_mask': + 'type': 'string' + 'example': '255.255.255.0' + 'range_start': + 'type': 'string' + 'example': '192.168.1.2' + 'range_end': + 'type': 'string' + 'example': '192.168.10.50' + 'lease_duration': + 'type': 'integer' + 'DhcpConfigV6': + 'type': 'object' + 'properties': + 'range_start': + 'type': 'string' + 'lease_duration': + 'type': 'integer' + 'DhcpLease': + 'type': 'object' + 'description': 'DHCP lease information' + 'required': + - 'mac' + - 'ip' + - 'hostname' + - 'expires' + 'properties': + 'mac': + 'type': 'string' + 'example': '00:11:09:b3:b3:b8' + 'ip': + 'type': 'string' + 'example': '192.168.1.22' + 'hostname': + 'type': 'string' + 'example': 'dell' + 'expires': + 'type': 'string' + 'example': '2017-07-21T17:32:28Z' + 'DhcpStaticLease': + 'type': 'object' + 'description': 'DHCP static lease information' + 'required': + - 'mac' + - 'ip' + - 'hostname' + - 'expires' + 'properties': + 'mac': + 'type': 'string' + 'example': '00:11:09:b3:b3:b8' + 'ip': + 'type': 'string' + 'example': '192.168.1.22' + 'hostname': + 'type': 'string' + 'example': 'dell' + 'DhcpStatus': + 'type': 'object' + 'description': 'Built-in DHCP server configuration and status' + 'required': + - 'config' + - 'leases' + 'properties': + 'enabled': + 'type': 'boolean' + 'interface_name': + 'type': 'string' + 'v4': + '$ref': '#/components/schemas/DhcpConfigV4' + 'v6': + '$ref': '#/components/schemas/DhcpConfigV6' + 'leases': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/DhcpLease' + 'static_leases': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/DhcpStaticLease' + 'DhcpSearchResult': + 'type': 'object' + 'description': > + Information about a DHCP server discovered in the current network. + 'properties': + 'v4': + '$ref': '#/components/schemas/DhcpSearchV4' + 'v6': + '$ref': '#/components/schemas/DhcpSearchV6' - This API request is ratelimited, so you can call it freely as often as you like, it wont create unneccessary burden on servers that host the URL. + 'DhcpSearchV4': + 'type': 'object' + 'properties': + 'other_server': + '$ref': '#/components/schemas/DhcpSearchResultOtherServer' + 'static_ip': + '$ref': '#/components/schemas/DhcpSearchResultStaticIP' + 'DhcpSearchV6': + 'type': 'object' + 'properties': + 'other_server': + '$ref': '#/components/schemas/DhcpSearchResultOtherServer' - This should work as intended, a `force` parameter is offered as last-resort attempt to make filter lists fresh. + 'DhcpSearchResultOtherServer': + 'type': 'object' + 'properties': + 'found': + 'type': 'string' + 'description': 'yes|no|error' + 'example': 'no' + 'error': + 'type': 'string' + 'description': 'Set if found=error' + 'example': '' + 'DhcpSearchResultStaticIP': + 'type': 'object' + 'properties': + 'static': + 'type': 'string' + 'description': 'yes|no|error' + 'example': 'yes' + 'ip': + 'type': 'string' + 'description': 'Set if static=no' + 'example': '' - If you ever find yourself using `force` to make something work that otherwise wont, this is a bug and report it accordingly. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/FilterRefreshRequest" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/FilterRefreshResponse" - /filtering/set_rules: - post: - tags: - - filtering - operationId: filteringSetRules - summary: Set user-defined filter rules - requestBody: - content: - text/plain: - schema: - type: string - example: "@@||yandex.ru^|" - description: All filtering rules, one line per rule - responses: - "200": - description: OK - /filtering/check_host: - get: - tags: - - filtering - operationId: filteringCheckHost - summary: Check if host name is filtered - parameters: - - name: name - in: query - description: Filter by host name - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/FilterCheckHostResponse" - /safebrowsing/enable: - post: - tags: - - safebrowsing - operationId: safebrowsingEnable - summary: Enable safebrowsing - responses: - "200": - description: OK - /safebrowsing/disable: - post: - tags: - - safebrowsing - operationId: safebrowsingDisable - summary: Disable safebrowsing - responses: - "200": - description: OK - /safebrowsing/status: - get: - tags: - - safebrowsing - operationId: safebrowsingStatus - summary: Get safebrowsing status - responses: - "200": - description: OK - content: - application/json: - examples: - response: - value: - enabled: false - /parental/enable: - post: - tags: - - parental - operationId: parentalEnable - summary: Enable parental filtering - requestBody: - content: - text/plain: - schema: - type: string - enum: - - EARLY_CHILDHOOD - - YOUNG - - TEEN - - MATURE - example: sensitivity=TEEN - description: | - Age sensitivity for parental filtering, - EARLY_CHILDHOOD is 3 - YOUNG is 10 - TEEN is 13 - MATURE is 17 - required: true - responses: - "200": - description: OK - /parental/disable: - post: - tags: - - parental - operationId: parentalDisable - summary: Disable parental filtering - responses: - "200": - description: OK - /parental/status: - get: - tags: - - parental - operationId: parentalStatus - summary: Get parental filtering status - responses: - "200": - description: OK - content: - application/json: - examples: - response: - value: - enabled: true - sensitivity: 13 - /safesearch/enable: - post: - tags: - - safesearch - operationId: safesearchEnable - summary: Enable safesearch - responses: - "200": - description: OK - /safesearch/disable: - post: - tags: - - safesearch - operationId: safesearchDisable - summary: Disable safesearch - responses: - "200": - description: OK - /safesearch/status: - get: - tags: - - safesearch - operationId: safesearchStatus - summary: Get safesearch status - responses: - "200": - description: OK - content: - application/json: - examples: - response: - value: - enabled: false - /clients: - get: - tags: - - clients - operationId: clientsStatus - summary: Get information about configured clients - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/Clients" - /clients/add: - post: - tags: - - clients - operationId: clientsAdd - summary: Add a new client - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Client" - required: true - responses: - "200": - description: OK - /clients/delete: - post: - tags: - - clients - operationId: clientsDelete - summary: Remove a client - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ClientDelete" - required: true - responses: - "200": - description: OK - /clients/update: - post: - tags: - - clients - operationId: clientsUpdate - summary: Update client information - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/ClientUpdate" - required: true - responses: - "200": - description: OK - /clients/find: - get: - tags: - - clients - operationId: clientsFind - summary: Get information about selected clients by their IP address - parameters: - - name: ip0 - in: query - description: Filter by IP address - schema: - type: string - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ClientsFindResponse" - /blocked_services/list: - get: - tags: - - blocked_services - operationId: blockedServicesList - summary: Get blocked services list - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/BlockedServicesArray" - /blocked_services/set: - post: - tags: - - blocked_services - operationId: blockedServicesSet - summary: Set blocked services list - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/BlockedServicesArray" - responses: - "200": - description: OK - /rewrite/list: - get: - tags: - - rewrite - operationId: rewriteList - summary: Get list of Rewrite rules - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/RewriteList" - /rewrite/add: - post: - tags: - - rewrite - operationId: rewriteAdd - summary: Add a new Rewrite rule - requestBody: - $ref: "#/components/requestBodies/RewriteEntry" - responses: - "200": - description: OK - /rewrite/delete: - post: - tags: - - rewrite - operationId: rewriteDelete - summary: Remove a Rewrite rule - requestBody: - $ref: "#/components/requestBodies/RewriteEntry" - responses: - "200": - description: OK - /i18n/change_language: - post: - tags: - - i18n - operationId: changeLanguage - summary: Change current language. Argument must be an ISO 639-1 two-letter code - requestBody: - content: - text/plain: - schema: - type: string - example: en - description: New language. It must be known to the server and must be an ISO 639-1 - two-letter code - responses: - "200": - description: OK - /i18n/current_language: - get: - tags: - - i18n - operationId: currentLanguage - summary: Get currently set language. Result is ISO 639-1 two-letter code. Empty - result means default language. - responses: - "200": - description: OK - content: - text/plain: - examples: - response: - value: en - /install/get_addresses: - get: - tags: - - install - operationId: installGetAddresses - summary: Gets the network interfaces information. - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/AddressesInfo" - /install/check_config: - post: - tags: - - install - operationId: installCheckConfig - summary: Checks configuration - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/CheckConfigRequest" - description: Configuration to be checked - required: true - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/CheckConfigResponse" - "400": - description: Failed to parse JSON or cannot listen on the specified address - /install/configure: - post: - tags: - - install - operationId: installConfigure - summary: Applies the initial configuration. - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/InitialConfiguration" - description: Initial configuration JSON - required: true - responses: - "200": - description: OK - "400": - description: Failed to parse initial configuration or cannot listen to the - specified addresses - "500": - description: Cannot start the DNS server - /login: - post: - tags: - - global - operationId: login - summary: Perform administrator log-in - requestBody: - content: - application/json: - schema: - $ref: "#/components/schemas/Login" - required: true - responses: - "200": - description: OK - /logout: - get: - tags: - - global - operationId: logout - summary: Perform administrator log-out - responses: - "302": - description: OK - /profile: - get: - tags: - - global - operationId: getProfile - summary: "" - responses: - "200": - description: OK - content: - application/json: - schema: - $ref: "#/components/schemas/ProfileInfo" - /apple/doh.mobileconfig: - get: - tags: - - mobileconfig - - global - operationId: mobileConfigDoH - summary: Get DNS over HTTPS .mobileconfig - responses: - "200": - description: DNS over HTTPS plist file + 'DnsAnswer': + 'type': 'object' + 'description': 'DNS answer section' + 'properties': + 'ttl': + 'type': 'integer' + 'example': 55 + 'type': + 'type': 'string' + 'example': 'A' + 'value': + 'type': 'string' + 'example': '217.69.139.201' + 'DnsQuestion': + 'type': 'object' + 'description': 'DNS question section' + 'properties': + 'class': + 'type': 'string' + 'example': 'IN' + 'host': + 'type': 'string' + 'example': 'example.org' + 'type': + 'type': 'string' + 'example': 'A' + 'AddUrlRequest': + 'type': 'object' + 'description': '/add_url request data' + 'properties': + 'name': + 'type': 'string' + 'url': + 'description': > + URL or an absolute path to the file containing filtering rules. + 'type': 'string' + 'example': 'https://filters.adtidy.org/windows/filters/15.txt' + 'whitelist': + 'type': 'boolean' + 'RemoveUrlRequest': + 'type': 'object' + 'description': '/remove_url request data' + 'properties': + 'url': + 'description': 'Previously added URL containing filtering rules' + 'type': 'string' + 'example': 'https://filters.adtidy.org/windows/filters/15.txt' + 'QueryLogItem': + 'type': 'object' + 'description': 'Query log item' + 'properties': + 'answer': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/DnsAnswer' + 'original_answer': + 'type': 'array' + 'description': 'Answer from upstream server (optional)' + 'items': + '$ref': '#/components/schemas/DnsAnswer' + 'upstream': + 'type': 'string' + 'description': > + Upstream URL starting with tcp://, tls://, https://, or with an IP + address. + 'answer_dnssec': + 'type': 'boolean' + 'client': + 'type': 'string' + 'example': '192.168.0.1' + 'client_proto': + 'enum': + - 'dot' + - 'doh' + - 'doq' + - '' + 'elapsedMs': + 'type': 'string' + 'example': '54.023928' + 'question': + '$ref': '#/components/schemas/DnsQuestion' + 'filterId': + 'type': 'integer' + 'example': 123123 + 'description': > + In case if there's a rule applied to this DNS request, this is ID of + the filter that rule belongs to. + 'rule': + 'type': 'string' + 'example': '||example.org^' + 'description': 'Filtering rule applied to the request (if any)' + 'reason': + 'type': 'string' + 'description': 'DNS filter status' + 'enum': + - 'NotFilteredNotFound' + - 'NotFilteredWhiteList' + - 'NotFilteredError' + - 'FilteredBlackList' + - 'FilteredSafeBrowsing' + - 'FilteredParental' + - 'FilteredInvalid' + - 'FilteredSafeSearch' + - 'FilteredBlockedService' + - 'ReasonRewrite' + 'service_name': + 'type': 'string' + 'description': 'Set if reason=FilteredBlockedService' + 'status': + 'type': 'string' + 'description': 'DNS response status' + 'example': 'NOERROR' + 'time': + 'type': 'string' + 'description': 'DNS request processing start time' + 'example': '2018-11-26T00:02:41+03:00' + 'QueryLog': + 'type': 'object' + 'description': 'Query log' + 'properties': + 'oldest': + 'type': 'string' + 'example': '2018-11-26T00:02:41+03:00' + 'data': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/QueryLogItem' + 'QueryLogConfig': + 'type': 'object' + 'description': 'Query log configuration' + 'properties': + 'enabled': + 'type': 'boolean' + 'description': 'Is query log enabled' + 'interval': + 'type': 'integer' + 'description': 'Time period to keep data (1 | 7 | 30 | 90)' + 'anonymize_client_ip': + 'type': 'boolean' + 'description': "Anonymize clients' IP addresses" + 'TlsConfig': + 'type': 'object' + 'description': 'TLS configuration settings and status' + 'properties': + 'enabled': + 'type': 'boolean' + 'example': true + 'description': 'enabled is the encryption (DOT/DOH/HTTPS) status' + 'server_name': + 'type': 'string' + 'example': 'example.org' + 'description': 'server_name is the hostname of your HTTPS/TLS server' + 'force_https': + 'type': 'boolean' + 'example': true + 'description': 'if true, forces HTTP->HTTPS redirect' + 'port_https': + 'type': 'integer' + 'format': 'int32' + 'example': 443 + 'description': 'HTTPS port. If 0, HTTPS will be disabled.' + 'port_dns_over_tls': + 'type': 'integer' + 'format': 'int32' + 'example': 853 + 'description': 'DNS-over-TLS port. If 0, DOT will be disabled.' + 'port_dns_over_quic': + 'type': 'integer' + 'format': 'int32' + 'example': 784 + 'description': 'DNS-over-QUIC port. If 0, DOQ will be disabled.' + 'certificate_chain': + 'type': 'string' + 'description': 'Base64 string with PEM-encoded certificates chain' + 'private_key': + 'type': 'string' + 'description': 'Base64 string with PEM-encoded private key' + 'certificate_path': + 'type': 'string' + 'description': 'Path to certificate file' + 'private_key_path': + 'type': 'string' + 'description': 'Path to private key file' + 'valid_cert': + 'type': 'boolean' + 'example': true + 'description': > + Set to true if the specified certificates chain is a valid chain of + X509 certificates. + 'valid_chain': + 'type': 'boolean' + 'example': true + 'description': > + Set to true if the specified certificates chain is verified and + issued by a known CA. + 'subject': + 'type': 'string' + 'example': 'CN=example.org' + 'description': 'The subject of the first certificate in the chain.' + 'issuer': + 'type': 'string' + 'example': "CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US" + 'description': 'The issuer of the first certificate in the chain.' + 'not_before': + 'type': 'string' + 'example': '2019-01-31T10:47:32Z' + 'description': > + The NotBefore field of the first certificate in the chain. + 'not_after': + 'type': 'string' + 'example': '2019-05-01T10:47:32Z' + 'description': > + The NotAfter field of the first certificate in the chain. + 'dns_names': + 'type': 'array' + 'items': + 'type': 'string' + 'description': > + The value of SubjectAltNames field of the first certificate in the + chain. + 'example': + - '*.example.org' + 'valid_key': + 'type': 'boolean' + 'example': true + 'description': 'Set to true if the key is a valid private key.' + 'key_type': + 'type': 'string' + 'example': 'RSA' + 'enum': + - 'RSA' + - 'ECDSA' + 'description': 'Key type.' + 'warning_validation': + 'type': 'string' + 'example': 'You have specified an empty certificate' + 'description': > + A validation warning message with the issue description. + 'valid_pair': + 'type': 'boolean' + 'example': true + 'description': > + Set to true if both certificate and private key are correct. + 'NetInterface': + 'type': 'object' + 'description': 'Network interface info' + 'properties': + 'flags': + 'type': 'string' + 'example': 'up|broadcast|multicast' + 'hardware_address': + 'type': 'string' + 'example': '52:54:00:11:09:ba' + 'name': + 'type': 'string' + 'example': 'eth0' + 'ipv4_addresses': + 'type': 'array' + 'items': + 'type': 'string' + 'ipv6_addresses': + 'type': 'array' + 'items': + 'type': 'string' + 'gateway_ip': + 'type': 'string' + 'AddressInfo': + 'type': 'object' + 'description': 'Port information' + 'properties': + 'ip': + 'type': 'string' + 'example': '127.0.0.1' + 'port': + 'type': 'integer' + 'format': 'int32' + 'example': 53 + 'AddressesInfo': + 'type': 'object' + 'description': 'AdGuard Home addresses configuration' + 'properties': + 'dns_port': + 'type': 'integer' + 'format': 'int32' + 'example': 53 + 'web_port': + 'type': 'integer' + 'format': 'int32' + 'example': 80 + 'interfaces': + 'type': 'object' + 'description': > + Network interfaces dictionary, keys are interface names. + 'additionalProperties': + '$ref': '#/components/schemas/NetInterface' + 'ProfileInfo': + 'type': 'object' + 'description': 'Information about the current user' + 'properties': + 'name': + 'type': 'string' + 'Client': + 'type': 'object' + 'description': 'Client information' + 'properties': + 'name': + 'type': 'string' + 'description': 'Name' + 'example': 'localhost' + 'ids': + 'type': 'array' + 'description': 'IP, CIDR or MAC address' + 'items': + 'type': 'string' + 'use_global_settings': + 'type': 'boolean' + 'filtering_enabled': + 'type': 'boolean' + 'parental_enabled': + 'type': 'boolean' + 'safebrowsing_enabled': + 'type': 'boolean' + 'safesearch_enabled': + 'type': 'boolean' + 'use_global_blocked_services': + 'type': 'boolean' + 'blocked_services': + 'type': 'array' + 'items': + 'type': 'string' + 'upstreams': + 'type': 'array' + 'items': + 'type': 'string' + 'ClientAuto': + 'type': 'object' + 'description': 'Auto-Client information' + 'properties': + 'ip': + 'type': 'string' + 'description': 'IP address' + 'example': '127.0.0.1' + 'name': + 'type': 'string' + 'description': 'Name' + 'example': 'localhost' + 'source': + 'type': 'string' + 'description': 'The source of this information' + 'example': 'etc/hosts' + 'ClientUpdate': + 'type': 'object' + 'description': 'Client update request' + 'properties': + 'name': + 'type': 'string' + 'data': + '$ref': '#/components/schemas/Client' + 'ClientDelete': + 'type': 'object' + 'description': 'Client delete request' + 'properties': + 'name': + 'type': 'string' + 'ClientsFindResponse': + 'type': 'array' + 'description': 'Response to clients find operation' + 'items': + '$ref': '#/components/schemas/ClientsFindEntry' + 'ClientsFindEntry': + 'type': 'object' + 'properties': + '1.2.3.4': + 'items': + '$ref': '#/components/schemas/ClientFindSubEntry' - /apple/dot.mobileconfig: - get: - tags: - - mobileconfig - - global - operationId: mobileConfigDoT - summary: Get TLS over TLS .mobileconfig - responses: - "200": - description: DNS over TLS plist file + 'ClientFindSubEntry': + 'type': 'object' + 'properties': + 'name': + 'type': 'string' + 'description': 'Name' + 'example': 'localhost' + 'ids': + 'type': 'array' + 'description': 'IP, CIDR or MAC address' + 'items': + 'type': 'string' + 'use_global_settings': + 'type': 'boolean' + 'filtering_enabled': + 'type': 'boolean' + 'parental_enabled': + 'type': 'boolean' + 'safebrowsing_enabled': + 'type': 'boolean' + 'safesearch_enabled': + 'type': 'boolean' + 'use_global_blocked_services': + 'type': 'boolean' + 'blocked_services': + 'type': 'array' + 'items': + 'type': 'string' + 'upstreams': + 'type': 'array' + 'items': + 'type': 'string' + 'whois_info': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/WhoisInfo' + 'disallowed': + 'type': 'boolean' + 'description': > + Whether the client's IP is blocked or not. + 'disallowed_rule': + 'type': 'string' + 'description': > + The rule due to which the client is disallowed. If disallowed is + set to true, and this string is empty, then the client IP is + disallowed by the "allowed IP list", that is it is not included in + the allowed list. -components: - requestBodies: - TlsConfig: - content: - application/json: - schema: - $ref: "#/components/schemas/TlsConfig" - description: TLS configuration JSON - required: true - DhcpStaticLease: - content: - application/json: - schema: - $ref: "#/components/schemas/DhcpStaticLease" - required: true - RewriteEntry: - content: - application/json: - schema: - $ref: "#/components/schemas/RewriteEntry" - required: true - schemas: - ServerStatus: - type: object - description: AdGuard Home server status and configuration - required: - - dns_address - - dns_port - - protection_enabled - - querylog_enabled - - running - - bootstrap_dns - - upstream_dns - - version - - language - properties: - dns_address: - type: string - example: 127.0.0.1 - dns_port: - type: integer - format: int32 - example: 53 - minimum: 1 - maximum: 65535 - protection_enabled: - type: boolean - dhcp_available: - type: boolean - querylog_enabled: - type: boolean - running: - type: boolean - version: - type: string - example: "0.1" - language: - type: string - example: en - DNSConfig: - type: object - description: Query log configuration - properties: - bootstrap_dns: - type: array - description: Bootstrap servers, port is optional after colon. Empty value will - reset it to default values - items: - type: string - example: - - 8.8.8.8:53 - - 1.1.1.1:53 - upstream_dns: - type: array - description: Upstream servers, port is optional after colon. Empty value will - reset it to default values - items: - type: string - example: - - tls://1.1.1.1 - - tls://1.0.0.1 - upstream_dns_file: - type: string - protection_enabled: - type: boolean - dhcp_available: - type: boolean - ratelimit: - type: integer - blocking_mode: - type: string - enum: - - default - - refused - - nxdomain - - null_ip - - custom_ip - blocking_ipv4: - type: string - blocking_ipv6: - type: string - edns_cs_enabled: - type: boolean - dnssec_enabled: - type: boolean - cache_size: - type: integer - cache_ttl_min: - type: integer - cache_ttl_max: - type: integer - upstream_mode: - enum: - - "" - - parallel - - fastest_addr - UpstreamsConfig: - type: object - description: Upstreams configuration - required: - - bootstrap_dns - - upstream_dns - properties: - bootstrap_dns: - type: array - description: Bootstrap servers, port is optional after colon. Empty value will - reset it to default values - items: - type: string - example: - - 8.8.8.8:53 - - 1.1.1.1:53 - upstream_dns: - type: array - description: Upstream servers, port is optional after colon. Empty value will - reset it to default values - items: - type: string - example: - - tls://1.1.1.1 - - tls://1.0.0.1 - Filter: - type: object - description: Filter subscription info - required: - - enabled - - id - - lastUpdated - - name - - rulesCount - - url - properties: - enabled: - type: boolean - id: - type: integer - example: 1234 - lastUpdated: - type: string - format: date-time - example: 2018-10-30T12:18:57+03:00 - name: - type: string - example: AdGuard Simplified Domain Names filter - rulesCount: - type: integer - example: 5912 - url: - type: string - example: https://adguardteam.github.io/AdGuardSDNSFilter/Filters/filter.txt - FilterStatus: - type: object - description: Filtering settings - properties: - enabled: - type: boolean - interval: - type: integer - filters: - type: array - items: - $ref: "#/components/schemas/Filter" - user_rules: - type: array - items: - type: string - FilterConfig: - type: object - description: Filtering settings - properties: - enabled: - type: boolean - interval: - type: integer - FilterSetUrl: - type: object - description: Filtering URL settings - properties: - data: - properties: - enabled: - type: boolean - name: - type: string - url: - type: string - type: object - url: - type: string - whitelist: - type: boolean - FilterRefreshRequest: - type: object - description: Refresh Filters request data - properties: - whitelist: - type: boolean - FilterCheckHostResponse: - type: object - description: Check Host Result - properties: - reason: - type: string - description: DNS filter status - enum: - - NotFilteredNotFound - - NotFilteredWhiteList - - NotFilteredError - - FilteredBlackList - - FilteredSafeBrowsing - - FilteredParental - - FilteredInvalid - - FilteredSafeSearch - - FilteredBlockedService - - ReasonRewrite - filter_id: - type: integer - rule: - type: string - example: "||example.org^" - description: Filtering rule applied to the request (if any) - service_name: - type: string - description: Set if reason=FilteredBlockedService - cname: - type: string - description: Set if reason=ReasonRewrite - ip_addrs: - type: array - items: - type: string - description: Set if reason=ReasonRewrite - FilterRefreshResponse: - type: object - description: /filtering/refresh response data - properties: - updated: - type: integer - GetVersionRequest: - type: object - description: /version.json request data - properties: - recheck_now: - description: If false, server will check for a new version data only once in - several hours - type: boolean - VersionInfo: - type: object - description: Information about the latest available version of AdGuard Home - properties: - new_version: - type: string - example: v0.9 - announcement: - type: string - example: AdGuard Home v0.9 is now available! - announcement_url: - type: string - example: https://github.com/AdguardTeam/AdGuardHome/releases/tag/v0.9 - can_autoupdate: - type: boolean - Stats: - type: object - description: Server statistics data - properties: - time_units: - type: string - description: Time units (hours | days) - example: hours - num_dns_queries: - type: integer - description: Total number of DNS queries - example: 123 - num_blocked_filtering: - type: integer - description: Number of requests blocked by filtering rules - example: 50 - num_replaced_safebrowsing: - type: integer - description: Number of requests blocked by safebrowsing module - example: 5 - num_replaced_safesearch: - type: integer - description: Number of requests blocked by safesearch module - example: 5 - num_replaced_parental: - type: integer - description: Number of blocked adult websites - example: 15 - avg_processing_time: - type: number - format: float - description: Average time in milliseconds on processing a DNS - example: 0.34 - top_queried_domains: - type: array - items: - $ref: "#/components/schemas/TopArrayEntry" - top_clients: - type: array - items: - $ref: "#/components/schemas/TopArrayEntry" - top_blocked_domains: - type: array - items: - $ref: "#/components/schemas/TopArrayEntry" - dns_queries: - type: array - items: - type: integer - blocked_filtering: - type: array - items: - type: integer - replaced_safebrowsing: - type: array - items: - type: integer - replaced_parental: - type: array - items: - type: integer - TopArrayEntry: - type: object - description: Represent the number of hits per key (domain or client IP) - properties: - domain_or_ip: - type: integer - StatsConfig: - type: object - description: Statistics configuration - properties: - interval: - type: integer - description: Time period to keep data (1 | 7 | 30 | 90) - DhcpConfig: - type: object - properties: - enabled: - type: boolean - interface_name: - type: string - v4: - $ref: "#/components/schemas/DhcpConfigV4" - v6: - $ref: "#/components/schemas/DhcpConfigV6" - DhcpConfigV4: - type: object - properties: - gateway_ip: - type: string - example: 192.168.1.1 - subnet_mask: - type: string - example: 255.255.255.0 - range_start: - type: string - example: 192.168.1.2 - range_end: - type: string - example: 192.168.10.50 - lease_duration: - type: integer - DhcpConfigV6: - type: object - properties: - range_start: - type: string - lease_duration: - type: integer - DhcpLease: - type: object - description: DHCP lease information - required: - - mac - - ip - - hostname - - expires - properties: - mac: - type: string - example: 00:11:09:b3:b3:b8 - ip: - type: string - example: 192.168.1.22 - hostname: - type: string - example: dell - expires: - type: string - example: "2017-07-21T17:32:28Z" - DhcpStaticLease: - type: object - description: DHCP static lease information - required: - - mac - - ip - - hostname - - expires - properties: - mac: - type: string - example: 00:11:09:b3:b3:b8 - ip: - type: string - example: 192.168.1.22 - hostname: - type: string - example: dell - DhcpStatus: - type: object - description: Built-in DHCP server configuration and status - required: - - config - - leases - properties: - enabled: - type: boolean - interface_name: - type: string - v4: - $ref: "#/components/schemas/DhcpConfigV4" - v6: - $ref: "#/components/schemas/DhcpConfigV6" - leases: - type: array - items: - $ref: "#/components/schemas/DhcpLease" - static_leases: - type: array - items: - $ref: "#/components/schemas/DhcpStaticLease" + 'WhoisInfo': + 'type': 'object' + 'properties': + 'key': + 'type': 'string' - DhcpSearchResult: - type: object - description: Information about a DHCP server discovered in the current network - properties: - v4: - $ref: "#/components/schemas/DhcpSearchV4" - v6: - $ref: "#/components/schemas/DhcpSearchV6" - - DhcpSearchV4: - type: object - properties: - other_server: - $ref: "#/components/schemas/DhcpSearchResultOtherServer" - static_ip: - $ref: "#/components/schemas/DhcpSearchResultStaticIP" - - DhcpSearchV6: - type: object - properties: - other_server: - $ref: "#/components/schemas/DhcpSearchResultOtherServer" - - DhcpSearchResultOtherServer: - type: object - properties: - found: - type: string - description: yes|no|error - example: no - error: - type: string - description: Set if found=error - example: "" - - DhcpSearchResultStaticIP: - type: object - properties: - static: - type: string - description: yes|no|error - example: yes - ip: - type: string - description: Set if static=no - example: "" - - DnsAnswer: - type: object - description: DNS answer section - properties: - ttl: - type: integer - example: 55 - type: - type: string - example: A - value: - type: string - example: 217.69.139.201 - DnsQuestion: - type: object - description: DNS question section - properties: - class: - type: string - example: IN - host: - type: string - example: example.org - type: - type: string - example: A - AddUrlRequest: - type: object - description: /add_url request data - properties: - name: - type: string - url: - description: URL or an absolute path to the file containing filtering rules - type: string - example: https://filters.adtidy.org/windows/filters/15.txt - whitelist: - type: boolean - RemoveUrlRequest: - type: object - description: /remove_url request data - properties: - url: - description: Previously added URL containing filtering rules - type: string - example: https://filters.adtidy.org/windows/filters/15.txt - QueryLogItem: - type: object - description: Query log item - properties: - answer: - type: array - items: - $ref: "#/components/schemas/DnsAnswer" - original_answer: - type: array - description: Answer from upstream server (optional) - items: - $ref: "#/components/schemas/DnsAnswer" - upstream: - type: string - description: Upstream URL starting with tcp://, tls://, https://, or with an IP address - answer_dnssec: - type: boolean - client: - type: string - example: 192.168.0.1 - client_proto: - enum: - - dot - - doh - - doq - - "" - elapsedMs: - type: string - example: "54.023928" - question: - $ref: "#/components/schemas/DnsQuestion" - filterId: - type: integer - example: 123123 - description: In case if there's a rule applied to this DNS request, this is ID of - the filter that rule belongs to. - rule: - type: string - example: "||example.org^" - description: Filtering rule applied to the request (if any) - reason: - type: string - description: DNS filter status - enum: - - NotFilteredNotFound - - NotFilteredWhiteList - - NotFilteredError - - FilteredBlackList - - FilteredSafeBrowsing - - FilteredParental - - FilteredInvalid - - FilteredSafeSearch - - FilteredBlockedService - - ReasonRewrite - service_name: - type: string - description: Set if reason=FilteredBlockedService - status: - type: string - description: DNS response status - example: NOERROR - time: - type: string - description: DNS request processing start time - example: 2018-11-26T00:02:41+03:00 - QueryLog: - type: object - description: Query log - properties: - oldest: - type: string - example: 2018-11-26T00:02:41+03:00 - data: - type: array - items: - $ref: "#/components/schemas/QueryLogItem" - QueryLogConfig: - type: object - description: Query log configuration - properties: - enabled: - type: boolean - description: Is query log enabled - interval: - type: integer - description: Time period to keep data (1 | 7 | 30 | 90) - anonymize_client_ip: - type: boolean - description: Anonymize clients' IP addresses - TlsConfig: - type: object - description: TLS configuration settings and status - properties: - enabled: - type: boolean - example: "true" - description: enabled is the encryption (DOT/DOH/HTTPS) status - server_name: - type: string - example: example.org - description: server_name is the hostname of your HTTPS/TLS server - force_https: - type: boolean - example: "true" - description: if true, forces HTTP->HTTPS redirect - port_https: - type: integer - format: int32 - example: 443 - description: HTTPS port. If 0, HTTPS will be disabled. - port_dns_over_tls: - type: integer - format: int32 - example: 853 - description: DNS-over-TLS port. If 0, DOT will be disabled. - port_dns_over_quic: - type: integer - format: int32 - example: 784 - description: DNS-over-QUIC port. If 0, DOQ will be disabled. - certificate_chain: - type: string - description: Base64 string with PEM-encoded certificates chain - private_key: - type: string - description: Base64 string with PEM-encoded private key - certificate_path: - type: string - description: Path to certificate file - private_key_path: - type: string - description: Path to private key file - valid_cert: - type: boolean - example: "true" - description: valid_cert is true if the specified certificates chain is a valid - chain of X509 certificates - valid_chain: - type: boolean - example: "true" - description: valid_chain is true if the specified certificates chain is verified - and issued by a known CA - subject: - type: string - example: CN=example.org - description: subject is the subject of the first certificate in the chain - issuer: - type: string - example: CN=Let's Encrypt Authority X3,O=Let's Encrypt,C=US - description: issuer is the issuer of the first certificate in the chain - not_before: - type: string - example: 2019-01-31T10:47:32Z - description: not_before is the NotBefore field of the first certificate in the - chain - not_after: - type: string - example: 2019-05-01T10:47:32Z - description: not_after is the NotAfter field of the first certificate in the chain - dns_names: - type: array - items: - type: string - description: dns_names is the value of SubjectAltNames field of the first - certificate in the chain - example: - - "*.example.org" - valid_key: - type: boolean - example: "true" - description: valid_key is true if the key is a valid private key - key_type: - type: string - example: RSA - description: key_type is either RSA or ECDSA - warning_validation: - type: string - example: You have specified an empty certificate - description: warning_validation is a validation warning message with the issue - description - valid_pair: - type: boolean - example: "true" - description: valid_pair is true if both certificate and private key are correct - NetInterface: - type: object - description: Network interface info - properties: - flags: - type: string - example: up|broadcast|multicast - hardware_address: - type: string - example: 52:54:00:11:09:ba - name: - type: string - example: eth0 - ipv4_addresses: - type: array - items: - type: string - ipv6_addresses: - type: array - items: - type: string - gateway_ip: - type: string - AddressInfo: - type: object - description: Port information - properties: - ip: - type: string - example: 127.0.0.1 - port: - type: integer - format: int32 - example: 53 - AddressesInfo: - type: object - description: AdGuard Home addresses configuration - properties: - dns_port: - type: integer - format: int32 - example: 53 - web_port: - type: integer - format: int32 - example: 80 - interfaces: - type: object - description: Network interfaces dictionary (key is the interface name) - additionalProperties: - $ref: "#/components/schemas/NetInterface" - ProfileInfo: - type: object - description: Information about the current user - properties: - name: - type: string - Client: - type: object - description: Client information - properties: - name: - type: string - description: Name - example: localhost - ids: - type: array - description: IP, CIDR or MAC address - items: - type: string - use_global_settings: - type: boolean - filtering_enabled: - type: boolean - parental_enabled: - type: boolean - safebrowsing_enabled: - type: boolean - safesearch_enabled: - type: boolean - use_global_blocked_services: - type: boolean - blocked_services: - type: array - items: - type: string - upstreams: - type: array - items: - type: string - ClientAuto: - type: object - description: Auto-Client information - properties: - ip: - type: string - description: IP address - example: 127.0.0.1 - name: - type: string - description: Name - example: localhost - source: - type: string - description: The source of this information - example: etc/hosts - ClientUpdate: - type: object - description: Client update request - properties: - name: - type: string - data: - $ref: "#/components/schemas/Client" - ClientDelete: - type: object - description: Client delete request - properties: - name: - type: string - ClientsFindResponse: - type: array - description: Response to clients find operation - items: - $ref: "#/components/schemas/ClientsFindEntry" - ClientsFindEntry: - type: object - properties: - 1.2.3.4: - items: - $ref: "#/components/schemas/ClientFindSubEntry" - - ClientFindSubEntry: - type: object - properties: - name: - type: string - description: Name - example: localhost - ids: - type: array - description: IP, CIDR or MAC address - items: - type: string - use_global_settings: - type: boolean - filtering_enabled: - type: boolean - parental_enabled: - type: boolean - safebrowsing_enabled: - type: boolean - safesearch_enabled: - type: boolean - use_global_blocked_services: - type: boolean - blocked_services: - type: array - items: - type: string - upstreams: - type: array - items: - type: string - whois_info: - type: array - items: - $ref: "#/components/schemas/WhoisInfo" - disallowed: - type: boolean - description: > - Whether the client's IP is blocked or not. - disallowed_rule: - type: string - description: > - The rule due to which the client is disallowed. - If `disallowed` is `true`, and this string is empty - it means that - the client IP is disallowed by the "allowed IP list", i.e. it is not included in allowed list. - - WhoisInfo: - type: object - properties: - key: - type: string - - Clients: - type: object - properties: - clients: - $ref: "#/components/schemas/ClientsArray" - auto_clients: - $ref: "#/components/schemas/ClientsAutoArray" - ClientsArray: - type: array - items: - $ref: "#/components/schemas/Client" - description: Clients array - ClientsAutoArray: - type: array - items: - $ref: "#/components/schemas/ClientAuto" - description: Auto-Clients array - RewriteList: - type: array - items: - $ref: "#/components/schemas/RewriteEntry" - description: Rewrite rules array - RewriteEntry: - type: object - description: Rewrite rule - properties: - domain: - type: string - description: Domain name - example: example.org - answer: - type: string - description: value of A, AAAA or CNAME DNS record - example: 127.0.0.1 - BlockedServicesArray: - type: array - items: - type: string - CheckConfigRequest: - type: object - description: Configuration to be checked - properties: - dns: - $ref: "#/components/schemas/CheckConfigRequestInfo" - web: - $ref: "#/components/schemas/CheckConfigRequestInfo" - set_static_ip: - type: boolean - example: false - CheckConfigRequestInfo: - type: object - properties: - ip: - type: string - example: 127.0.0.1 - port: - type: integer - format: int32 - example: 53 - autofix: - type: boolean - example: false - CheckConfigResponse: - type: object - properties: - dns: - $ref: "#/components/schemas/CheckConfigResponseInfo" - web: - $ref: "#/components/schemas/CheckConfigResponseInfo" - static_ip: - $ref: "#/components/schemas/CheckConfigStaticIpInfo" - CheckConfigResponseInfo: - type: object - properties: - status: - type: string - example: "" - can_autofix: - type: boolean - example: false - CheckConfigStaticIpInfo: - type: object - properties: - static: - type: string - example: no - description: "Can be: yes, no, error" - ip: - type: string - example: 192.168.1.1 - description: Current dynamic IP address. Set if static=no - error: - type: string - example: "" - description: Error text. Set if static=error - InitialConfiguration: - type: object - description: AdGuard Home initial configuration (for the first-install wizard) - properties: - dns: - $ref: "#/components/schemas/AddressInfo" - web: - $ref: "#/components/schemas/AddressInfo" - username: - type: string - description: Basic auth username - example: admin - password: - type: string - description: Basic auth password - example: password - Login: - type: object - description: Login request data - properties: - username: - type: string - description: User name - password: - type: string - description: Password - Error: - description: A generic JSON error response. - properties: - message: - type: string - description: The error message, an opaque string. - type: object + 'Clients': + 'type': 'object' + 'properties': + 'clients': + '$ref': '#/components/schemas/ClientsArray' + 'auto_clients': + '$ref': '#/components/schemas/ClientsAutoArray' + 'ClientsArray': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/Client' + 'description': 'Clients array' + 'ClientsAutoArray': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/ClientAuto' + 'description': 'Auto-Clients array' + 'RewriteList': + 'type': 'array' + 'items': + '$ref': '#/components/schemas/RewriteEntry' + 'description': 'Rewrite rules array' + 'RewriteEntry': + 'type': 'object' + 'description': 'Rewrite rule' + 'properties': + 'domain': + 'type': 'string' + 'description': 'Domain name' + 'example': 'example.org' + 'answer': + 'type': 'string' + 'description': 'value of A, AAAA or CNAME DNS record' + 'example': '127.0.0.1' + 'BlockedServicesArray': + 'type': 'array' + 'items': + 'type': 'string' + 'CheckConfigRequest': + 'type': 'object' + 'description': 'Configuration to be checked' + 'properties': + 'dns': + '$ref': '#/components/schemas/CheckConfigRequestInfo' + 'web': + '$ref': '#/components/schemas/CheckConfigRequestInfo' + 'set_static_ip': + 'type': 'boolean' + 'example': false + 'CheckConfigRequestInfo': + 'type': 'object' + 'properties': + 'ip': + 'type': 'string' + 'example': '127.0.0.1' + 'port': + 'type': 'integer' + 'format': 'int32' + 'example': 53 + 'autofix': + 'type': 'boolean' + 'example': false + 'CheckConfigResponse': + 'type': 'object' + 'properties': + 'dns': + '$ref': '#/components/schemas/CheckConfigResponseInfo' + 'web': + '$ref': '#/components/schemas/CheckConfigResponseInfo' + 'static_ip': + '$ref': '#/components/schemas/CheckConfigStaticIpInfo' + 'CheckConfigResponseInfo': + 'type': 'object' + 'properties': + 'status': + 'type': 'string' + 'example': '' + 'can_autofix': + 'type': 'boolean' + 'example': false + 'CheckConfigStaticIpInfo': + 'type': 'object' + 'properties': + 'static': + 'type': 'string' + 'example': 'no' + 'description': 'Can be: yes, no, error' + 'ip': + 'type': 'string' + 'example': '192.168.1.1' + 'description': 'Current dynamic IP address. Set if static=no' + 'error': + 'type': 'string' + 'example': '' + 'description': 'Error text. Set if static=error' + 'InitialConfiguration': + 'type': 'object' + 'description': > + AdGuard Home initial configuration for the first-install wizard. + 'properties': + 'dns': + '$ref': '#/components/schemas/AddressInfo' + 'web': + '$ref': '#/components/schemas/AddressInfo' + 'username': + 'type': 'string' + 'description': 'Basic auth username' + 'example': 'admin' + 'password': + 'type': 'string' + 'description': 'Basic auth password' + 'example': 'password' + 'Login': + 'type': 'object' + 'description': 'Login request data' + 'properties': + 'username': + 'type': 'string' + 'description': 'User name' + 'password': + 'type': 'string' + 'description': 'Password' + 'Error': + 'description': 'A generic JSON error response.' + 'properties': + 'message': + 'description': 'The error message, an opaque string.' + 'type': 'string' + 'type': 'object'