Merge pull request #15 from shoddyguard/update_documentation

Prepare module for v.0.2.0 release

.rufo

@@ -0,0 +1 @@
+quote_style  :single

CHANGELOG.md

@@ -4,10 +4,11 @@ All notable changes to this project will be documented in this file.
 
 ## Release 
 
-### [v0.1.1](https://github.com/shoddyguard/Puppet-Adguard/tree/v0.1.1) (2020-04-01)
+### [v0.2.0](https://github.com/shoddyguard/Puppet-Adguard/tree/v0.2.0) (2020-04-01)
 
 **Features**
 - Moved several complex types into their own definitions rather than defining them in the parameters of the main class.
+- Added a new function for validating TLS options
 - Moved default parameter declarations from hiera into the manifests. This allows Puppet-Strings to extract default values into documentaion and makes things easier to locate.
 - Tidied up documentation and added some more examples
 - Expanded acceptance testing slightly

README.md

@@ -136,6 +136,73 @@ class {'adguard':
 ```
 For more information on this please see the [official AdGuard documentation](https://github.com/AdguardTeam/AdGuardHome/wiki/Clients#newclient)
 
+## Configuring DHCP
+AdGuard Home supports acting as a DHCP server and as of v0.2.0 this module allows for configuration of those options.  
+To enable DHCP you would need to set `enable_dhcp` to `true`, specify a `dhcp_interface` and then specify your `dhcp_v4_options`/`dhcp_v6_options`  
+Example:  
+```puppet
+class {'adguard':
+    users => [{
+        username => 'user',
+        password => '$2y$10$c6lDDShTh5ezcvKhyWwOMet6C/0tLxlgYX53wf58jl9tBdUVbYSqe',
+    }],
+    enable_dhcp => true,
+    dhcp_interface => 'eth0',
+    dhcp_v4_options => {
+      gateway_ip => '192.168.1.1',
+      subnet_mask => '255.255.255.0',
+      range_start => '192.168.1.2',
+      range_end => '192.168.1.20',
+      lease_duration => 86400, # in seconds
+    }
+```
+If you'd like to enable special DHCP options this can be done via the `options` parameter, these should be given as `CODE hex HEX_VALUE` (eg `6 hex 0102030401020305`).  
+```puppet
+class {'adguard':
+    users => [{
+        username => 'user',
+        password => '$2y$10$c6lDDShTh5ezcvKhyWwOMet6C/0tLxlgYX53wf58jl9tBdUVbYSqe',
+    }],
+    enable_dhcp => true,
+    dhcp_interface => 'eth0',
+    dhcp_v4_options => {
+      gateway_ip => '192.168.1.1',
+      subnet_mask => '255.255.255.0',
+      range_start => '192.168.1.2',
+      range_end => '192.168.1.20',
+      lease_duration => 86400, # in seconds
+      options => [
+        '6 hex 0102030401020305'
+      ],
+    }
+```
+For more information see the official [AdGuard documentation](https://github.com/AdguardTeam/AdGuardHome/wiki/DHCP#config-4)
+
+## TLS Configuration
+As of v0.2.0 this module now supports setting the TLS settings in Adguard. This remains largely untested so use with caution and please report any issues on the module repository.  
+A basic configuration would look like:
+```puppet
+class {'adguard':
+    users => [{
+        username => 'user',
+        password => '$2y$10$c6lDDShTh5ezcvKhyWwOMet6C/0tLxlgYX53wf58jl9tBdUVbYSqe',
+    }],
+    enable_tls => true,
+    tls_options => {
+        server_name => 'adguard-test.com',
+        force_https => false,
+        port_https => 443,
+        port_dns_over_tls => 853,
+        port_dns_over_quic => 784,
+        port_dnscrypt => 0,
+        allow_unencrypted_doh => false,
+        strict_sni_check => false,
+        certificate_path => '/root/cert.pem',
+        private_key_path => '/root/key.pem',
+    }
+```
+More information on these settings can be found in the [official AdGuard docs](https://github.com/AdguardTeam/AdGuardHome/wiki/Encryption)
+
 # Know Limitations
 ## Configuration overwriting itself/Disabling configuration file management
 Due to the fact this module manages configuration of AdGuard by manipulating the `AdGuardHome.yaml` file there may be instances where Puppet fights against AdGuard Home with both trying to change the contents of the file. 

metadata.json

@@ -1,6 +1,6 @@
 {
   "name": "shoddyguard-adguard",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "author": "Steve Brown",
   "summary": "Manages AdGuard Home",
   "license": "Apache-2.0",

spec/acceptance/dhcp_spec.rb

@@ -0,0 +1,41 @@
+# Tests applying adguard with basic DHCP options
+require 'spec_helper_acceptance'
+
+describe 'adguard_dhcp' do
+  it 'applies succesfully' do
+    dhcp_pp = <<-MANIFEST
+    class {'adguard':
+        users => [
+          {
+              username => 'user',
+              password => '$2y$10$c6lDDShTh5ezcvKhyWwOMet6C/0tLxlgYX53wf58jl9tBdUVbYSqe',
+          }],
+        enable_dhcp => true,
+        dhcp_interface => 'eth0',
+        dhcp_v4_options => {
+            gateway_ip => '192.168.1.1',
+            subnet_mask => '255.255.255.0',
+            range_start => '192.168.1.2',
+            range_end => '192.168.1.20',
+            lease_duration => 86400,
+        }
+    }
+MANIFEST
+    idempotent_apply(dhcp_pp)
+  end
+
+  describe service('AdGuardHome') do
+    it { is_expected.to be_enabled }
+    it { is_expected.to be_running }
+  end
+
+  describe file('/opt/AdGuardHome/AdGuardHome.yaml') do
+    it { is_expected.to be_file }
+    it { is_expected.to contain %r{interface_name: eth0} }
+    it { is_expected.to contain %r{gateway_ip: 192.168.1.1} }
+    it { is_expected.to contain %r{subnet_mask: 255.255.255.0} }
+    it { is_expected.to contain %r{range_start: 192.168.1.2} }
+    it { is_expected.to contain %r{range_end: 192.168.1.20} }
+    it { is_expected.to contain %r{lease_duration: 86400} }
+  end
+end

spec/acceptance/tls_spec.rb

@@ -2,10 +2,12 @@
 # Only basic configuration is checked as unsure how to test more extensively in a container.
 require 'spec_helper_acceptance'
 
-# Copy over a dummy SSL cert + key (generated by OpenSSL) to use for testing SSL,
-# this expires on 2022/04/02, unsure if this will cause errors in the future.
-# This also only tests the "path" options for TLS and not specifying the certs directly, we should implement this later.
-pp_tls = <<-MANIFEST
+describe 'adguard_tls' do
+  it 'applies succesfully' do
+    # Copy over a dummy SSL cert + key (generated by OpenSSL) to use for testing SSL,
+    # this expires on 2022/04/02, unsure if this will cause errors in the future.
+    # This also only tests the "path" options for TLS and not specifying the certs directly, we should implement this later.
+    pp_tls = <<-MANIFEST
     $ca_cert = @("CA_CERT"/L)
 -----BEGIN CERTIFICATE-----
 MIIFcjCCA1oCCQDRZO9ndAf3hTANBgkqhkiG9w0BAQsFADB7MQswCQYDVQQGEwJH
@@ -126,22 +128,24 @@ class {'adguard':
     }
 MANIFEST
 
-idempotent_apply(pp_tls)
-
-describe 'adguard_tls' do
-  context service('AdGuardHome') do
+    idempotent_apply(pp_tls)
+  end
+  describe service('AdGuardHome') do
     it { is_expected.to be_enabled }
     it { is_expected.to be_running }
   end
-  # Ensure our ports are listening
-  context port(80) do
-    it { is_expected.to be_listening }
-  end
-  context port(53) do
-    it { is_expected.to be_listening }
-  end
-  context file('/opt/AdGuardHome/AdGuardHome.yaml') do
+
+  describe file('/opt/AdGuardHome/AdGuardHome.yaml') do
     it { is_expected.to be_file }
-    its(:content) { is_expected.to match(%r{server_name: adguard-test.com}) }
+    it { is_expected.to contain %r{server_name: adguard-test.com} }
+    it { is_expected.to contain %r{force_https: false} }
+    it { is_expected.to contain %r{port_https: 443} }
+    it { is_expected.to contain %r{port_dns_over_tls: 853} }
+    it { is_expected.to contain %r{port_dns_over_quic: 784} }
+    it { is_expected.to contain %r{port_dnscrypt: 0} }
+    it { is_expected.to contain %r{allow_unencrypted_doh: false} }
+    it { is_expected.to contain %r{strict_sni_check: false} }
+    it { is_expected.to contain %r{certificate_path: /root/cert.pem} }
+    it { is_expected.to contain %r{private_key_path: /root/key.pem} }
   end
 end