80.1、kea-dhcp4.conf

// 这是 Kea DHCPv4 服务器的一个基本设置。
// 大多数的子网声明均被注释掉了，且没有列举任何接口。因此，服务器不会监听或回应任何请求。
// 基础配置必须被扩展，至少要指定服务器应该监听的接口。下面有一些例子选项。可能它们对于你的网络并没有什么意义。
// 在你的网络中运行这个案例之前，请保证至少更新了如下的内容：
// - 修改了网络接口的名字
// - 修改了子网，以匹配你实际的网络
// - 修改了选项值，以匹配了你的网络
//
// 这是非常基础的配置。Kea 有很多的（超过 30 个）配置案例，以及详尽的 Kea 用户指引。
// 请参考这些材料，来更好地了解本软件都可以做什么。本配置的注释有时会指向一些 section 来展示更多细节。
// 它们是 Kea 用户指引的 section 号。与你软件版本匹配的用户指引应该随软件一同安装了，
// 但也可以从 ISC 的知识库（https://kea.readthedocs.io）获取（稳定版的直达链接是 https://kea.readthedocs.io/）。
//
// 本配置文件仅包含 DHCPv4 服务器的配置。
// 若其它 Kea 服务的配置也包含在了这个文件中，那么那些配置会被 DHCPv4 服务器忽略
{
  // DHCPv4 配置从此处开始。本段会被 DHCPv4 服务器读取，且会被其它组件忽略。
  "Dhcp4": {
    // 添加要监听的网络接口的名称
    "interfaces-config": {
      // 查看 section 8.2.4 来了解详请。
      // 可以直接添加接口名（比如 "eth0"），
      // 或者同时指定接口名上的 IP 地址（比如 "eth0/192.0.2.1"）。
      "interfaces": []
      // 默认情况下，DHCPv4 服务器会监听raw sockets。
      // 它保证了可以接收所有的包，包括那些直连的，还没有 IPv4 地址的客户端发出的包。
      // 若你的流量总是被中继，那么使用常规的 UDP sockets 会是更好的选择。
      // 如果你想这样做，去掉下面者行的注释：
      // "dhcp-socket-type": "udp"
    },
    // Kea 支持控制通道，它是一种在服务器运行时接收控制命令的方法。
    // 它是一个 UNIX 域 socket，接收 JSON 格式的命令，比如
    // config-set（设置新的配置），
    // config-reload（让 Kea 从文件重载配置），
    // statistic-get（获得统计），等等。
    // 详细的说明，参见 section 8.8、16 和 15。
    "control-socket": {
      "socket-type": "unix",
      "socket-name": "/tmp/kea4-ctrl-socket"
    },
    // 使用 Memfile 租用数据库后端将租用数据存储为 CSV 文件。
    // 基于 Kea 的编译情况，Kea 还可以支持 SQL 数据库（MySQL 和/或 PostgreSQL）。
    // 这些数据库后端要求更多的参数，比如 name、host，可能还需要 user 和 password。
    // 下方是为每个后端准备的例子。参见 section 7.2.2 "Lease Storage" 了解详情。
    "lease-database": {
      // Memfile 是最简单也最简易的后台。它是一个内存中的 C++ 数据库，
      // 同时，它还会以硬盘上的一个 CSV 文件存储租用数据。
      "type": "memfile",
      "lfc-interval": 3600
    },
    // Kea 允许在一个数据库中存放主机保留（host reservations）信息。
    // 若你的网络较小，或你的 reservation 较小，那么将它们存放在配置文件中会比较简单。
    // 若你的网络很大，那么最好是用一个数据库来存储。要启用它，去掉下面的注释。
    // "hosts-database": {
    //     "type": "mysql",
    //     "name": "kea",
    //     "user": "kea",
    //     "password": "kea",
    //     "host": "localhost",
    //     "port": 3306
    // },
    // 参见 section 7.2.3 "Host storage" 来了解详情。
    // 设置对于过期租用和租用 affinbity 的 reclamation。
    // 每 10 秒会执行过期租用的回收。
    // 若租用已经过期超过 3600 秒，那么每 25 秒已被回收的租用会被移除。
    // lease reclamation 的限制为 100 个租用，或单次循环 250ms。
    // 若 5 个连续的 reclamation 循环之后，数据库中依旧有过期租用，就会记录一个警告信息。
    "expired-leases-processing": {
      "reclaim-timer-wait-time": 10,
      "flush-reclaimed-timer-wait-time": 25,
      "hold-reclaimed-time": 3600,
      "max-reclaim-leases": 100,
      "max-reclaim-time": 250,
      "unwarned-reclaim-cycles": 5
    },
    // 此处定义的全局计时器会运用在所有的子网中，
    // 若特定的子网指定了自己的计时器，则会覆盖全局计时器。
    "renew-timer": 900,
    "rebind-timer": 1800,
    "valid-lifetime": 3600,
    // 此处还能指定很多其它的参数：
    // - option 定义（若你想指定 vendor option，你自定义的 option，
    //                或者 Kea 还没有开箱即用的标准 option）
    // - 客户端类型
    // - 钩子
    // - ddns 信息（DHCPv4 组件如何访问一个 DDNS 进程）
    //
    // 有一些选项在下方有例子，但还包含其它参数。
    // 参考 Kea 用户指引来了解它们。
    // 这些都是全局 option。当客户端请求它们的时候，会被发送，除非在更特定的作用域下覆盖了这些值。
    // 作用域的层级关系为：
    // - global（最通用，可以被 class、subnet、host 覆盖）
    // - class（可以被 subnet 或 host 覆盖）
    // - subnet（可以被 host 覆盖）
    // - host（最特定的，会覆盖其它的作用域）
    //
    // 并非所有的选项都有意义。请仅配置那些在你网络中确实有用的。
    //
    // 要查看当前 Kea 支持的 option 的完整列表，参见 section 7.2.8 "Standard DHCPv4 Options"。
    // Kea 也支持 vendor options（参见 section 7.2.10），而且允许用户定义自定义的 option（参见 section 7.2.9）。
    "option-data": [
      // 当指定 option 的时候，你通常需要指定一个名称（或代码）以及对应的数据。
      // option 的完整定义包含 name、code、space、csv-format 以及 data。
      // space 的默认值 "dhcp4" 通常是正确的，除非你使用了 encapsulate option。
      // csv-format 的默认值为 "true"，通常也是正确的，除非你想将整个 option 的值以十六进制字符串表示。
      // 比如说，要指定 domian-name-servers，你可以这样做：
      // {
      //     "name": "domain-name-servers",
      //     "code": 6,
      //     "csv-format": "true",
      //     "space": "dhcp4",
      //     "data": "192.0.2.1, 192.0.2.2"
      // }
      // 不过上面这种太麻烦了，它还可以这样写：
      {
        "name": "domain-name-servers",
        "data": "192.0.2.1, 192.0.2.2"
      },
      // 通常情况下，人们喜欢使用名称来指代 option，因此也不需要记住代码号。
      // 但是，也有一些人喜欢用数字值。比如，option "domain-name" 对应的代码号是 15，
      // 所以，你可以用 "name": "domain-name"，或者 "code": 15。
      {
        "code": 15,
        "data": "example.org"
      },
      // Domain search 也是一个常见的 option。它告诉客户端在这些指定的域中解析名称。
      // 举例来说，名称 "foo" 会首先以 foo.mydomain.example.com 进行解析，若失败，
      // 那么就尝试 foo.example.com
      {
        "name": "domain-search",
        "data": "mydomain.example.com, example.com"
      },
      // 若字符串类型的 options 的值具有逗号，
      // 那么逗号需要被转义（比如，在每个逗号前追加两个反斜线）。
      // 这是因为逗号被用于在复合选项中间隔两个字段，于此同时，
      // 我们还得满足 JSON 的定义，json 不允许 "\,"。
      // 因此需要不那么常见的双反斜线。
      // 有效的 JSON 转义包括反斜线后紧接如下字符 "\/bfnrt"，
      // 或者 \u 后跟随 4 个十六进制数字（目前 Kea 仅支持 \u0000 至 \u00ff 码点）。
      // CSV 处理过程将 '\\' 转义为 '\'，将 '\,' 转义为 ','，例外是 '\x' 会被转义为 '\x'。
      // 但由于其处理的是 JSON 字符串值，每个反斜线字符都应该在 JSON 输入中写作两个反斜线。
      {
        "name": "boot-file-name",
        "data": "EST5EDT4\\,M3.2.0/02:00\\,M11.1.0/02:00"
      },
      // 接受整型值的 option 可以用十进制或十六进制表示。
      // 十六进制值可以是纯值（比如 abcd），或前缀 0x（比如 0xabcd）。
      {
        "name": "default-ip-ttl",
        "data": "0xf0"
      }
      // 注意 Kea 会自行提供一些 option。具体来说，
      // IP 地址租用类型（code 51，基于 valid-lifetime 参数）、
      // 子网掩码（code 1，基于子网定义）、
      // 刷新时间（code 58，基于 renew-timer 参数）、
      // 重绑定时间（code 59，基于 rebind-timer 参数）。
    ],
    // 其它可以在此处定义的全局参数是 option 定义（比如 vendor option、自定义的 option、
    //                                              或者 Kea 还未开箱即用的 option）。
    // 你还可以定义类型 class。若定义了类型，那么来包可以被赋予特定的类型。
    // 一个客户端类型可以表示一组具有某种共通特性的设备，
    // 比如 Windows 设备、iphone、需要特殊选项的陈旧打印机，等等。
    // 基于类型信息，你可以允许或禁止客户端使用特定的子网，为它们追加特定的 option，或
    // 修改某些固定字段的值。
    "client-classes": [
      {
        // 指定类别的名称，若你需要引用该类会很有用
        "name": "voip",
        // 测试条件。该表达式会对每个来包进行匹配。测试结果要么为真，要么为假。
        // 若为真，则该包被添加至特定的类型。参见 section 12 以获得可用的表达式。
        // 它们有好几十个。section 8.2.14 有 DHCPv4 分类，section 8.2.19 中 DHCPv6 的。
        "test": "substring(option[60].hex,0,6) == 'Aastra'",
        // 若一个客户端属于该类型，你就可以定义额外的行为。
        // 比如，DHCPv4 包中的特定字段会被设置为特定的值。
        "next-server": "192.0.2.254",
        "server-hostname": "hal9000",
        "boot-file-name": "/dev/null"
        // 若你希望该类型的设备接受特定的 option，你还可以在此处定义 option 的值。
      }
    ],
    // 另一个可以定义的是钩子。Kea 支持一种强大的机制，允许载入外部库来抽取信息，甚至影响
    // 服务器处理包的过程。这些库包含额外的取证日志功能，以更灵活的方式指定 reserve hosts，
    // 甚至是添加额外的命令。可用钩子的列表，参见
    // https://gitlab.isc.org/isc-projects/kea/wikis/Hooks-available
    // "hooks-libraries": [
    //   {
    //       // 取证日志库可以生成由 Kea 服务的全部设备的审计轨迹的取证类型，
    //       // 包含它们的身份（比如 MAC 地址），它们在网络中的位置，它们活跃的次数等等。
    //       "library": "/usr/lib64/kea/hooks/libdhcp_legal_log.so",
    //       "parameters": {
    //           "path": "/var/lib/kea",
    //           "base-name": "kea-forensic4"
    //       }
    //   },
    //   {
    //       // Flexible Identifier（flex-id）。Kea 软件提供了一种方法来处理主机保留，
    //       // 包含地址、前缀、选项、客户类型和其它功能。reservation 可以基于
    //       // 硬件地址、DUID、DHCPv4 中的 circuit-id 或 client-id。
    //       // 但有时候，reservation 的情况会更加复杂，
    //       // 比如，使用上面提到的选项、使用特定选项的部分值，
    //       // 甚至是使用多个选项和字段的组合来唯一确定一个客户端。
    //       // 这些情景都可以通过 Flexible Identifier 钩子应用实现。
    //       "library": "/usr/lib64/kea/hooks/libdhcp_flex_id.so",
    //       "parameters": {
    //           "identifier-expression": "relay4[2].hex"
    //       }
    //   }
    // ],
    // 下方是一个简单的 IPv4 子网声明。去注释以启用它。它是一个用 [ ] 表示的列表，
    // 其中的每个项用 { } 表示。每一项都是一个子网，它可能具有数个参数。
    // 其中一个参数是 "pools"，它也是一个由项组成的列表。
    "subnet4": [
      {
        // 该参数确定了整个子网。Kea 将使用这个信息来判定客户端是否链接。
        // 它是你网络中的整个子网。该参数是每个子网的必要参数。
        "subnet": "192.0.2.0/24",
        // pools 定义了子网中实际被 Kea 管理的部分。
        // 技术上来说，它是一个可选参数，但它几乎总是 DHCP 正常工作需要的参数。
        // 若你忽略它，除非为主机定义了主机保留，否则客户端就无法获得地址。
        "pools": [
          {
            "pool": "192.0.2.1 - 192.0.2.200"
          }
        ],
        // 此处为子网特定的 option。在大多数情况下，你至少需要定义 routers option，
        // 若无这个 option，你的客户端将无法到达它们的默认网关，也就无法获得互联网连接。
        "option-data": [
          {
            // 对于每个 IPv4 子网，你可能需要指定至少一个 router。
            "name": "routers",
            "data": "192.0.2.1"
          }
        ],
        // Kea 提供了主机保留机制。Kea 支持通过几种不同的类型的标识来执行保留：
        // hw-address（客户端的硬件/MAC 地址）、duid（客户端插入的 DUID）、
        // client-id（客户端插入的客户端标识符）、circuit-id（中继代理插入的客户端标识符）。
        //
        // Kea 也支持 flexible identifier（flex-id），它允许你用一个表达式
        // 对每个来包进行判别。返回值可以用来作为标识符。
        //
        // 注意，在 Kea 中，保留是子网特定的。这与 ISC DHCP 不同。
        // 在迁移你的设置时，请谨记于心。
        "reservations": [
          // 这是为特定 硬件/MAC 地址做的保留。
          // 它是一个较为简单的保留：就是一个地址，没有其它内容。
          {
            "hw-address": "1a:1b:1c:1d:1e:1f",
            "ip-address": "192.0.2.201"
          },
          // 它是为特定 client-id 做的保留。它也表示该客户端会获得一个保留的主机名。
          // 主机名可以为任意标识类型定义，并非只有 client-id。
          {
            "client-id": "01:11:22:33:44:55:66",
            "ip-address": "192.0.2.202",
            "hostname": "special-snowflake"
          },
          // The third reservation is based on DUID. This reservation defines
          // a special option values for this particular client. If the
          // domain-name-servers option would have been defined on a global,
          // subnet or class level, the host specific values take preference.
          // 第三种保留是基于 DUID 的。这种保留为特定的客户端设置了特别的 option 值。
          // 即便 domain-name-servers option 已在 global、subnet、class 级别定义，
          // host 级别定义的值依旧会优先使用。
          {
            "duid": "01:02:03:04:05",
            "ip-address": "192.0.2.203",
            "option-data": [
              {
                "name": "domain-name-servers",
                "data": "10.1.1.202, 10.1.1.203"
              }
            ]
          },
          // 第四个保留是基于 circuit-id 的。它是由用于把客户端的包转发至服务器的
          // 中继代理插入的选项。在这个案例中，主机还被赋予了 vendor 特定的选项。
          //
          // 使用保留时，同时配置 reservations-global、reservations-in-subnet、
          // reservations-out-of-pool（子网特定参数）、host-reservation-identifiers（全局参数）
          // 会很有用。
          {
            "client-id": "01:12:23:34:45:56:67",
            "ip-address": "192.0.2.204",
            "option-data": [
              {
                "name": "vivso-suboptions",
                "data": "4491"
              },
              {
                "name": "tftp-servers",
                "space": "vendor-4491",
                "data": "10.1.1.202, 10.1.1.203"
              }
            ]
          },
          // 该保留用于一个需要特别设置 DHCPv4 字段的客户端。
          // 三个支持的字段是 next-server、server-hostname、boot-file-name
          {
            "client-id": "01:0a:0b:0c:0d:0e:0f",
            "ip-address": "192.0.2.205",
            "next-server": "192.0.2.1",
            "server-hostname": "hal9000",
            "boot-file-name": "/dev/null"
          },
          // 该保留使用了 flexible identifier。
          // 它不依赖于特定的字段，系统管理员可以定义一个与客户端分类类似的表达式，
          // 比如 substring(relay[0].option[17],0,6)，然后基于来包在该表达式判断后的值，
          // 来做保留的匹配。表达式可以通过十六进制或者单引号的明文指定。
          //
          // 注意：flexible identifier 要求载入了 flex_id 钩子库才能工作。
          {
            "flex-id": "'s0mEVaLue'",
            "ip-address": "192.0.2.206"
          }
          // 你可以在此处添加更多的保留。
        ]
        // 你可以在此处添加更多的子网。
      }
    ],
    // DHCPv4 server 还有很多很多可以用的参数。它们并没有添加到此处，
    // 以防止一次性灌输过多信息。
    // 日志配置从这里开始。Kea 使用不同的日志记录来记录器各种活动。
    // 详细信息（比如记录器的名称）参见 18 章。
    "loggers": [
      {
        // 本段影响的是 kea-dhcp4，它是 DHCPv4 组件的基础记录器。
        // 它告诉 DHCPv4 服务器将所有的（等于或高于 INFO 严重度的）日志信息写入一个文件。
        "name": "kea-dhcp4",
        "output_options": [
          {
            // 指定输出文件。它还支持一些特殊值：
            // - stdout（打印到标准输出）
            // - stderr（打印到标准错误）
            // - syslog（记录至 syslog）
            // - syslog:name（使用特定的名称记录至 syslog）
            // 其它的值都被认为是一个文件名
            "output": "/var/log/kea-dhcp4.log"
            // 较短的日志样式适用于使用 systemd，以避免冗余信息。
            // "pattern": "%-5p %m\n",
            // 它规定了日志输出是否在每次写入后刷写到硬盘上。
            // "flush": false,
            // 指定了文件被轮转前的最大大小。
            // "maxsize": 1048576,
            // 指定了保留的轮转文件的最大数量。
            // "maxver": 8
          }
        ],
        // 指定了日志信息要保留的严重级别。支持的值包括：
        // FATAL、ERROR、WARN、INFO、DEBUG
        "severity": "INFO",
        // 若使用了 DEBUG 级别，则该值启用。 0 表示最简洁，99 表示最详细。
        // 特别小心，Kea 可能会在你的要求下，产生非常非常多的日志。
        "debuglevel": 0
      }
    ]
  }
}