piholectl

用于管理 Pi-Hole 实例的命令行工具

用法

$ piholectl help
piholectl 0.2.0
Command line tool to manage Pi-Hole instances

USAGE:
    piholectl [OPTIONS] <SUBCOMMAND>

OPTIONS:
    -c, --config-file-path <CONFIG_FILE_PATH>
            Path to config file

    -g, --groups <GROUPS>
            Named groups to use from the config file

    -h, --help
            print help message

        --hosts <HOSTS>
            Hosts to manage

    -j, --json
            Output as JSON

        --keys <KEYS>
            API key for a pihole instance. Anything with a length < 10 is considered no key

    -v, --verbose
            Be verbose

    -V, --version
            Print version information

SUBCOMMANDS:
    all-queries               DNS query data
    cache                     Cache statistics
    client-names              Hostname and IP for clients
    cname                     Custom DNS records
    disable                   Disable ad blocking
    dns                       Custom DNS records
    enable                    Enable ad blocking
    forward-destinations      Percentage of queries forwarded to each target
    help                      Print this message or the help of the given subcommand(s)
    list                      Show/Modify a black/whitelist
    logage                    Logage info
    network                   Network clients
    over-time-data-clients    Get queries over time by client
    over-time10-min           Number of queries, binned into 10 minute blocks
    queries-count             Total number of queries
    query-types               Number of queries per type
    summary                   Get summary information
    summary-raw               Get raw (numerical) summary information
    top-clients               Clients with the most queries
    top-clients-blocked       Clients with the most blocked queries
    top-items                 Most queries items
    version                   Simple PiHole Version
    versions                  Versions of core, FTL and web and if updates are available

每个命令都提供帮助信息。

$ piholectl list help
piholectl-list 
Show/Modify a black/whitelist

USAGE:
    piholectl list <LIST> <SUBCOMMAND>

ARGS:
    <LIST>    List to use Acceptable lists are: `white`, `black`, `white_regex`, `black_regex`,
              `white_wild`, `black_wild`, `audit`

OPTIONS:
    -h, --help    Print help information

SUBCOMMANDS:
    add       
    help      Print this message or the help of the given subcommand(s)
    remove    
    show    

可以指定多个主机作为参数。主机/密钥对按顺序匹配，即第 n 个主机将与第 n 个密钥匹配。必须指定密钥，但长度小于 10 个字符的任何内容都视为 "None"，并且只能执行未认证的查询。

$ piholectl --hosts 'https://127.0.0.1' --keys <API Key> --hosts 'http://127.0.0.1' --keys none enable`
+------------------+---------+
| Host             | status  |
+------------------+---------+
| https://127.0.0.1 | enabled |
+------------------+---------+

Errors:
http://127.0.0.1: MissingAPIKey

配置

配置文件可以存储常用组合，这些组合将除了命令行选项中指定的任何主机外还将被查询。默认情况下使用特定平台的配置文件位置。使用 -v 或 --verbose 运行将输出搜索路径。
JSON 配置文件包含具有可选密钥以及组的命名主机列表。组包含要查询的命名主机列表。如果命令行选项中没有指定组（可以指定多个），则使用名为 default 的组。

{
  "hosts": {
    "test_with_key": {
      "host": "https://127.0.0.1",
      "key": "<API KEY>"
    },
    "test_no_key": {
      "host": "http://127.0.0.1"
    }
  },
  "groups": {
    "default": [
      "test_with_key",
      "test_no_key"
    ],
    "example_group": [
      "test_no_key"
    ]
  }
}

例如，使用上述配置文件将生成以下输出

$ # no group is specified, "default" group is used
$ piholectl enable
+------------------+---------+
| Host             | status  |
+------------------+---------+
| https://127.0.0.1 | enabled |
+------------------+---------+

Errors:
http://127.0.0.1: MissingAPIKey

$ # "example_group" group is specified so "default" group is not added automatically
$ piholectl enable -g example_group
+------------------+---------+
| Host             | status  |
+------------------+---------+
| https://127.0.0.1 | enabled |
+------------------+---------+

Errors:
http://127.0.0.1: MissingAPIKey

# Group "example_group" is used in addition to the manually specified host
$ piholectl -g example_group --hosts 'http://192.168.0.54' --keys none enable
+------+--------+
| Host | status |
+------+--------+

Errors:
http://192.168.0.54: MissingAPIKey
http://127.0.0.1: MissingAPIKey

JSON 输出

可以使用 -j 或 --json 将输出设置为 JSON。

$ piholectl -j list black show
{
  "https://127.0.0.1": {
    "Ok": [
      {
        "id": 255,
        "type": 1,
        "domain": "example.net",
        "enabled": false,
        "date_added": 1657367855,
        "date_modified": 1657367855,
        "comment": "chom",
        "groups": [
          0
        ]
      },
      {
        "id": 256,
        "type": 1,
        "domain": "example.com",
        "enabled": false,
        "date_added": 1657367898,
        "date_modified": 1657367898,
        "comment": "",
        "groups": [
          0
        ]
      }
    ]
  },
  "http://127.0.0.1": {
    "Err": "MissingAPIKey"
  }
}