From 2564aa085e078d3a9ad86f925582f2fc7684066d Mon Sep 17 00:00:00 2001 From: DL6ER Date: Tue, 1 May 2018 15:01:46 +0200 Subject: [PATCH 1/6] Add FTLDNS landing page Signed-off-by: DL6ER --- docs/ftldns/index.md | 7 +++++++ docs/images/FTLDNS.png | Bin 0 -> 19684 bytes mkdocs.yml | 1 + 3 files changed, 8 insertions(+) create mode 100644 docs/ftldns/index.md create mode 100644 docs/images/FTLDNS.png diff --git a/docs/ftldns/index.md b/docs/ftldns/index.md new file mode 100644 index 0000000..9a18ec0 --- /dev/null +++ b/docs/ftldns/index.md @@ -0,0 +1,7 @@ +

+FTLDNS
+

+ +*FTL*DNS[™](https://pi-hole.net/trademark-rules-and-brand-guidelines/) (`pihole-FTL`) offers DNS services within the Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) project. +It provides DNS and DHCP services (it can also provide TFTP and more) as well as an interactive API where generated statistics for 's Web interface can be queried. The internal DNS server is based on the popular `dnsmasq`. + diff --git a/docs/images/FTLDNS.png b/docs/images/FTLDNS.png new file mode 100644 index 0000000000000000000000000000000000000000..2e314636b040b676f81e6c22a06b23711a00b6ba GIT binary patch literal 19684 zcmd?RgbI3=B!?vzRg%7(~tcc@r%3`zMJH%J};ixRbJ^ z2w24!;os_}3u+9!Jc~$;8p>i?bEbp7hVSM#exFXMS?>KZO3z-@o{Dwle<@C3~m; z5$jz*z@Huf3llToe?v2KxB9=J{ptC?qM4ffAE~~$INJUrlc@>7%+}1#%--4Q9gpRI zCHJn||AYAdV$$8{%fE>Iqr`v7#`lMF9%VBppsmXv6{y);ISa7z{UgwSH~&W?|H2Xl z+I?{}b8>n|6JY-zl)u~l8(#B2WCS?>P2=yz|3*-7w0f7+=nr24EdN8`@3#Mj*ZSWG z{N4B$!XMT1C|bFj*=mYey({z|DLA;9`2hcG&wpcz0&RhgDqoCD%>Hop56WLn{|)^Q z9j*V+Vd47pH=VzF{=zgh;c;>?wl*_y{>xtPR{Ll6ix^n|{%Ym}{IAe_?{k4i4rpp+ z?jdI6Y$m|U%)-UU%*M#Vt;)j9!_3C>>D_Ms1@jjNe|kh6&5WFZj;cVQt-wEG*!{UA zWn<#}7v|sn|AWd0_~S=^`PILi_Mg^wuN8oQ$NcvSAOO$!!C3+fObAR$Ojy+&{4@(8 zlfbO))#B@keG86fEf(tc2?*o7q$j;jg6>NQx{}<%w#)+J@i&@$RWtDtPQEoEs7TUW zOEf4TO}@}C9PP6tWg6H*U3fdU#+Kz(Io7xRG}DGf+pnXo8B*q7_fPldWzE-)-PYu? zpZ7S=HIu)>hWr2j`Je?~uFD;Y_)71C+(ue)XXZI8N@Sz}{k3$q#q zKHzI{Q&A0eZ!c*U*$>4jZhVykL~gp?4_CYU+_BT&3>3%{?gvy9_+4yXea~M?Vm)AP z=pe{R|9vQWLGYf|O)K9RuhZR7B9Rf?EiIa*=&gN|rJ8p?zt+#;IsBgJ8nhs{e|qo52K2`bd6KIzEM?lL$+ma)f2uk7=>PK3DU+Rb4Ercnvg zzJHBw2yyW(88ZR3+6mS7f=oqB3+*|HWvC;KrLOPl^B^`w!OMSSo9Kk>zY0Z{qf2^B z|DoZ!pXK(-JancH&l1bYsMByF*LOu3Ni^}-=%@ip82-7>=uFoNc%{_Q>>(G+wL;N|OTr;T9Gy zz%k`lATtAvIvFI4db#$ljHP+lYri9^Xr<~B4-C~%A2(e)aCfhL0is{%JN)tSHq zt808)t8Gb)u+VFEvtf5J{%sr7014_Us z7kf|y`2uR7H0Xr%G(-snV>6mpny-%;=WzBC<421N@BW$`8<3<-2=H1bZf!-2^>#qU zU^xB7Yf^#J6%#<~MK^U7(Dh8fzMvhvwFv@e;2n@KXC$LHRZtLXB`rtlT>RfAdbbsR z7?{}Zj7UM>>*nyAyY_+x{BBn}zxjB!Ppez>nx-wzuos@#CBjICPNN3L6MoC<<1zLA zsnfdjAa;Jf&tEJpKt_6)a=L3?)KxuIzet|@tQ~t~5@(5i#silA^5nEUZa9g zf2j0Zyf`n^69rj@7f0P+HX-jEeufI6n25ee@1}oZ2CXW>;vI1TN7LD#eejXFzn@vyAb+vHk86x=O_Vdf) zouJQF1hxJcf2gN~yO&cO*75%r8}oKhBsKObUEt+rn%@7UnS6l?b7399=<)RVMF-gC zqC}=MBFaFPp`i4a4RQnEOo3DBs<7a#Mf@Qkll6I{ALIiPClW+BCWV0-k|(_x%fJr) zh?Ljo7jFQWPIx5f?-e$h^h*yCr(!R*v#W?AD0VQ@r`GfKNbRCVU*$maOkn4*OB!l@ zbTy?VW*h2w;Fb2*L+fc^)(!HJ+JF4-C=+a+Yj;YXs0uCWe*U2;3K?i98elAv zI6$g6K5$89pYmDI`|3A!*nIxzxP~kZg+Z6VSy2y05viA5`I{UG-DQ_)o zcnlE{(K@~3$SM+9E1X^QP@oUg6D1ihe3I**d#g|%?8UGnbhJUyCwnIYuep1u^p@4o zyV0s5h<<>kZ(g#^ar_+|F3DR7B}9x+E>zG8LW5xRR#GLKkuQ3s>UE80*Zo9mTaXeiwk=K3U#rMqyyELl=`nXiSFBweJ59h zUXaUB9W+%P`ct&HgMR9U%&lUc(9v$DlC-NaV^;%;h0_qK_jl47+5wLsF(QjDdH>5W zqxvb3Wq9(F&rnBWpOzPTWr8efqDrI-Aw=WOJ`4$G#_iBm=1x%zYJuR;s*)vvhv%ek zo+#AQ46_I}IjCo&21v&0(r_M7-JjTyxqX3%{JKe>L~1y2Lh_AE_c4CcyEbdV$!zUL ztJ#MLDY6r-wUO)^qgnazLz5;GA{^Iix%m zHPdH8!xKcG1+TwU?o44eHy`Ou5~9SwVoSg^4r6m8^AW>6FG3&BF*UQa60ot z=hoFORp+8nes%hiyVLzzPh1_GR%?=LZ<)&GY-M+jRliUfo;KjaB*4=rKhyotxv?xO zm1q!E{|)Ym@kByXPnWoli!K3I!-GEB7}O`NTEf#W?r;2P!>n&)mMWh*t?L}?N)|1M z?FZ3<%>jnsLPv$ac$l1=%o1V?s;(7e!=qecQuh;%vlT7VM)kUxYy)@7hnpx#ifGv? zb+7blX+iN1kHHzwqo6d@nY+GzddlI^}ldiAb>0=f)t3J)94g{L1+mdg{jAJWeDU)ctU5Gc>!R@Mf&PY7s=5d zuhyv$||z^nF*^J59W8!j^TNON?fMO) zN537epkRkwQy4%2n&-hfP6-Obwnc7o5)Zj*b~%=K0kaIBfLK}Rl@URTM^*RVn4kKc z5YLD-$d4bT^-=Vbw3?B?y0HvA-_K@M6&@-GVT=v46+llrm`NsyI3vGtOggBy^9|7p zhv5KlEn$`^c&1=HfMS>#b^8t1;7tqnt%xq|{=+xHrYjW|fQ7HX`OA4V%Mp-hZR%SJ zS&2s7rA;snpH|6hQBjeSpPLK7^gZfaC|tjP>qB&8ZYEra+C6iRfZ0hm?_wwUl9ZemvsT$oxjGwcBSbG-39=3%jW@<>@S&LE9Ivx&6H|Kk1^4#Fxti_yvO|F8 z57$T`ci4%COREJs+%_qfbHpxOgu*z({YC_$iS|e|E)w?H+VGDwucXTO)B(*nHCEJ% zs76qj1{T>~XBdThqEk||Wx1H7=c#t9Hg2v(ZH>PAqx%_KCNE#q*V5k=zedv4v_g_X zX4C7;0nOim2BROs;s<5tT@QacQxh>id2e977~pBuau&j%E^7-*cDyjhZxRLQ8%Vwj z8`d=GG38k&^olTwqN9SSr@Y|!)Q$-Hq3xO$%Z}h8NZjJ%bk-}vT$Px0iRt!Y--{bV z8m)hjVAQ}mO27-uo7ysGR+98}#l{i!2ee^%{BcgsvQEn)^_&=O%z!CKTtJa*5>=~ht;XUbav{>*_)b&+L$)!+Dj1$b zC)~-w3j^yJp*vD?=v}+rJXwmaBIgnu+R1eATaUS&LwN}%NN?uzhl&l&hnvy2GD9Du zib#C~xJCHvyk_hg&8_jf82zR?KGX432Otz4r?Xl^7dL5DFjm|~9NgP=jEM_6BN`#S zR|O@6I9w~9Ha3TnbY21 zb@eU;&nIc88S!?EIUTNcIp>aa%#od2httbM16u$)12{pdxtwOhE|YfnS+3ec?;g#Z z?DhFO<(QVrJ#kW4h*sH=D)Rn#4&|*;Y3<*+&uqRBHB%X@G*W8|@HvOgST%E<{+mRP z+R#6gooru1k)8@Fg3llOt7A*g8|c)8uFI7v)f9ZtHa=MS!j-O{r%&!jnY1C#S>|CC zNPTMz(?5}rdci%ojbUA|j+yQlEKwitUyaqWE!w8hcUU>7#ad8bIx**s5~Rv^y-r;8 zt~E&o{*Xq~;3r3whG^QH_R02c6D*{~5jgMcfa@o@Ui}4A#~%om)BG@o<`wAIQ|jZ^ zlO0eV%8#-Pxt*j5FDHO#fgZg-!FK*)zc4UMyVoh}o9Q5LDF7z&QDqfgYe1qkUx6`r zxK-ZE>q$>tL*pYJ=NCQmEheX0B0-t_MAgqA%GS<`1x@1@^TL-kiDn-+nBJ0eb5V|Y!-YI04V%&BjJaNU5--c-?gKv zz#+$d9<=0*k7WQ^5bymfTH?M@gN{YlTyP<0K z3^MyC3h=uaLC7~4SG=;X#6iR}cX4H#ed);CJ%sXsm%vIzPbgj>t+UWmzhq}GyFfd3 zsiJ39@xI}wZ9iLh`jUl3tq#YJZ>iLe6%!4~V+IYjgKod@v6-`h$)m$M?>AyAhz}(f z#JK#5B%yX6mf=8HxE-=KN#^;R*EX~6NXsAZ-b##~jO@}=j@O9{_i^cj6b==Pk}#`7 znnz%0USRt(=GNf1*Y$m2!MBSNnG4}DE&w39l>pM8wRq}=@m1OT=t0JG%Kl*6CI~0Q zPAMkh0EtEScJVLeD=Z4Rtieg0wFe6!RYZoxUD^J#0qsJ8?6526rMnAxl*TgFKQSWLmRtiD>#gdqxCY@(3i}H8rn3D$v4*I{Fu0ylN*X7`EWUx z!VfVKAEPA*-2+%)Xid)`uD> z@UULsQQv)qJWQB90#g%6tGBJFm`i9oz39PESoIhPfEF^C@yv#viNt0>cRLi*Szc9l zdyV`kPVnO)z+t3OZf@n*aF8aw+Yw3eR4oXcFL%>pC72_a9;vO#BE10{#0RSEI!0(P z=|GPf$o6{4s_fu`-?3W^X*=&U+m~nD5r|aqIo}{51^8W!k(39=#CS^`m!`~#FiPmjT8_?I?!+dHGS;unT4V%hbteIhA`dwAbtCdr zFfV|1dmVcD^D}*elCi2YwrpU7i=V&EuIm6*-`3&TO{^<|ea<#Jjy6UPd1&A0)I!*g zGej==Dd~3B!<@wI?q@$lh&!Vl&n6p*`2zQQa-jU+clmDuh^}07Ms+U&^y8&sm1q>5 z7l98|)+@}{EOpoA;g>&D-QtABb3*l$f520yj|=&~tU|fG@pnF|xrD>cB*nXAepAv6 zAgaA-eS()8a^|seMrJjFntWt=55}v?D7)bU@#w`4>E+SeH3#tOpf|L3AJI^AF)Q57 zA~$Cnw$w-L8yZ79SMj~pdT26Qx+P@2N*Al?x${H%8J97PLsV+f8F&5 zuA$d4#qzwJYrH>~CevC5$&yI!#?YDmz9q-)i6-97fR+K6v;vVWM_ThLl>A5`gFm&- z&Z$M09eQT7@K#f{7Sm|+%M_0iOQ1zb0%u{TAD|iW7QAJOrz?Nqrzy{diq&64TKJ2$ zbW{yW?9+{#7Mg4bdH{CD0?5Ye5pckyX^!>==j zl>vN5aRyNoKCKht2|pKU|2Pn$wxNUlrPSw`bSlG*j?j7zQvVbP!fU>n7ZUKf%AcZQ zx%R;fe2O<1L|ZA0nX1PM1i0?qK<-_DL??~FTqLzN1cqCmCr|dvb}BGvE*kGHuJ}~h z%*53;i{3Qtx6|X*Z0(4zw3es2UP6>f8a*3k;|ppde>jgn3U-->PMcu~qr0M`a8~trG7&F=yps`>c%giZ=!n%b$g`>apeHuwAql#+54ir|!b4{|8 z(y+ePPbO*z`)H>W9zsFiGQF7wCgHMKNsO4i3^t z{q2T6OfMcRwCW9x#A9Ba_C;LIBZu$=a^9UC$Vd}za}ETvR2fu~^`Sa5FkVjQ zYAkt=V71_4R7ViD=?N(M660>gPjXziP;K%$#^Xy;Cz*U;-j&=XFvux=EA?*8GP@>M ztC3j1k8u^9Af>{QZg}JBgZJA+7ElvJH$ft=>x!^-g~h4qpHTIScAhQDt{>-H+SZ_? z(y`D4vJx@H&W6cFpTIo#E{vZuvI^Wk2+U$z=~0|XE!?AwiZNL8=W>Z2JXLDGqe zEWn!Wb#038)*&}?&?5v!9RZ_OkX11p{qJ_8;#}LXX?2_Hf&l>Q5{YNrFMHMA1KD2V z$(F@2)Aj(b<{t&y6}k7dYZZ4cc0$i*P8aF+R#X;F?$o_BV&@mjtel!E82oMF1w`HR zr(*Y$?XwN7rvQv(g@vw|EImYzQi86bUc5Bhwu3`6@H~}VU)7AP6b`Olz$yCAkUuJ_aTWclzOfF%xNv!$%c?1aZG9nroJ0x}ydBK_1NK7Lm z<39$CchhtSO1BPOR^-y5D7Cd3*EJ2jY+7hkf2~$mM+UN+``CE%}s&l zR0GX%>lesS!rqN6qB`xe!|>r3pC^jbx81p(D(HyCd_oF$e+4N|_DBrTEs_*7tCi0Ef0A?c10|ME5byBa3M2g{D2ms5Y{E70~{43FN8<+hiAQt zq%Lz;>(zq_Z7PHhdg$+#&o87iA(BNF2;9r=*+!z#XS-sj&~JOc zG?)elN4&f7I_Lqf+g+|8!W|O-R3A#6&@O1GzOv#dN!73}GmM=3J{USKcb2V{lXUymA%XG8Yc_qfD2WEphp8%XwK!u ztSl&~=>zrdYU-QoQ`fry=wO%elBll_Uy}o4ao#*yOls?S#pvdvN5hk3HAQ|h9O<`t z?@o6U@{!qMtkr4aG*npfk8bhQB086d4~46PezS!>m`jXJ#(e@()*o15F70?`Mx!9n zjUxWs@;`p@D|w6cU&>9n;L(&6x(&CUr5D=O1 zXryl)vAMb3KJl~S>xU{4O*u)u9ZVBF%n7bA5$Azq{8BPW`vus*Mz8gqzU!PL6BsVp z#^xpHci}Tq_XR~AGj}|}Z#$UpN`P_vZm!aLrEFWT>iM%5`UVWkQl8S_FL+hkE7jF)34xicb2Uqb z7-ez?r`UqSRD_2;zJ=Y8_k&CCj_8vx&ah&8aOW6H1mlGY+5_|CC2+ZV+DHVSAxfru zi;mSrp%|#5@>R~vX7{xA1AD?^7$k8k(YIoNNWiIy9vykoCbAhhbMWpX2>|M8!X}#d z@dvljO@6E;Xv?iZWy7ZpV{ne$^p5(-JeT146H@V7)XmgiK1NOtjj2-_Zeo(HsfLlV0~AcZ)hppAYEy%ak6xA zRzzy1Q%+Uqr?qTi_arjX9;m)Gh(icFH~wu|B95JZ@|(L3Pu3cSq?;3TCXs_TH06nD zSulZQ8S{f|pkCZ*qOJO>gu5y;pU6*KiJkuB7cG0`0!F+_F^Q+81 z?Gyt8T?xKfi5r-!mkHkLD8(Dh>3DBX?hJ$-XQCO-1B6$XAvOKVOZN(&FbtanFw=Uk zg;|~;qB+A(Ays~|27E?Xlv`cZZTYkv@PoA}H$A8hx5i?miL>O9Uhn)diT+L^>y;n1 zq2BpDNv-tQSu?V)lQch+g{&0{sc@8oTFL{PCqc$Dbj#n}l8#o(fbI53X0CIZRqX@T zdkP>EZy~iG#;&z*(~61aNiVanTeT(%b6-@b1-FqQtbB4^c{3Bio;vHn<y9J!# z+N25Hhi+xsbBW-)WCL+9!}u+ZQ6seTRGdVc1*EE*=1;xo*i5|SvHKGkL7BZC^)B3^ z-f{dwe>gGi!7YS_*I?V7Yz}j5k|^H5pY&&R7h!)gv>BJxYO;ucrqSE(smg?i9|ar3 z;lHYRMZn2(B%oD0^RxUAasH7|nWZGxZg{=)LGXtNmLN zn)F2~PDW1{@BAXiqPY|X3}Q%WPpH9njjWqHKc3z?qjR`t z69-)mgem(&lGB^Mv3j{86y5uR*Zh#0jm02RD4brDid*RN6&6-Pte4Ml&H0n%6^wlV zJ*Iv55U0_09wtgdUbyw+ctcMwW&$j`^s22U4OwLbS-ABKtlAC2KDimz?V&P|bl0h~ zb@;L%Y|rObk;i<8;<~rGondXMSYDU?QplF8p9~tMd$@~BGyJ-@x%Y0v;T549#o9zs?!w*T)?Rod=9doL9kvO6i;CnTTbIjy$!)cRXMMlEwhJ~z>Z;s zH0?dTx-VpN#33XjK#}`ismfOLUYOSP>~C4?&h49IRd)*wdY`3}RvVNgJn0>-Rqni6 z=6e#o&E}{N1vwV`FK0TO6*GF9z3sIK3d7XZmLlGHhj zSrJ!+rhFar8u7_!o(mdKCXY4H%(azh_ER@JfnPV*I&@3%d+Jnun0oRGeW8KU?1V*Gw#K>p+i{wgXzUxoXW^1b0$~ywM)~ET*tQr8riz4N}5Tmv^_|K;SRl{TQj)-&0ZB zU}tUpSj@KQkyG21=Wmt@F_0|fAyRL;OY;F(d&fQ4#PJcWgc7{pOJDgnywg!L*fMa` z!=N$)U}zZD)&Al7b*O-A&S%o9VrJVbDTfBRA>9Wg&{?`@9bhsH&X;|zmqQXfo|L<%J zCu5u~`L}Uif~@5lW7k0>tU;{uGQb;uTcvj_?)iEBYDiyN6d8oRd^;f1emHXBcJ6zT z^K{M^B16Am^a+X)W{6O^rcH(T?A zgMAm+?4L^!*{$v0?&c08DxLGoPtUH7P$Vn<-`;66YEh%DNiWc=npVWfOIeJNZI!Q4yR>S(jySER(fWT9z!b{b@#_T{%}<3$Jq5 z(|aK8bo!cJnIuzrQmC#nj>cap_qhB$#9j5QkjrAmUWaloxqResg&avTN8i(&vzv`~ zb`6Idw57@FYV0ZcXx%Ef)HX8CZo}Vb>D!jJv=weHCxY0x#1AU2I<}>EGQrm|i%5tN zNzzyOUX+sV8(CN%yCtXRjWAr-tNbh#i?8c&HrqS@Y}Y<6mmRiLeKxpSewq&%crz%m z-BU@E{uKrn@bq!vPG*mlw+XBdS7vBp84fja*55&aQ*<@5n5s|a@60M#^0~V7m&xZmIlGgNimf{%gnT+E= zj&EvNDNn;U&H!l{LE;=(K>5nf2A$Txd&00lZJ21N^qFnqH-XX3$lTKk%8fVXQxi(v zON=K>8f{jK1jpt@@6K-vF%b2khi}M_#f8T$9N8y2MvL`xR*s zc>L9ScEZ@sSwwxeuhq2GDoa%LS?etp=Lr`xuSnT*R6A0E)zq|XI%_S_@zL8#O&6!y znxd5-G02@;j#Y>}teeys)M-+i%(q-oOV=G=s?t)ICUbQ3Uw-A!okAk-oH`NwKH1*3 zr7cM@HlXmRm2d>z$&1X9RIaRK7E<@j?VgoQfb2^wj6#kgjoEd#F4(Hx z_S}>(dGPlHVqZmIoq)AIJsPBbUH8)W?T-1_8HYChYU8#b6Y^|JE#=#a*jnM92M){8 zREIaNj0#pXW_pqv745LZf5gXvJ_ih}VnXL2B^0x4}$-Km65O8pdWY!F7$_EPG` z@K{#+%{_iTe)8HE9&zPv%(WMQ;Gi&Xd*lz0N`OPlY`fiEO(f3x)HhU76+expp~_Kd zCxBhbn0WwA68+Iw2@vcckF_{jRzf5Y|NCp80uMBI8~mGr4(0wAG&@9$RQ6W2hnRgj z12Y;MQ@&#bhyy$ekQ#I1lO)7}{AlS;OvAO&&D7Pcyyj~$xN8V`7EYwTSRFsuE;UM#eN0-`0_`BG1*TW7oy2b$k*!tXC4kYNaYh^z@}3IIO3;|Q zh!&F{-0F`OmFvgvTaZn3P%o4nVkjfUM#yU-_>g+&9aMsl6Thp8XYB93h;+Vo;mwow zifgRKDcbEZY!M?I#51W9#I0pF!yH`fDp!XgKlH$#FQ@b5dd>@f^(A6;GZfD~-&uxC zT{P}gta0qa%7<@>X*=*sdpH?_;pr$M{3AL%-$@&Fel3@=Osh+5n8zX+^*Y2ip;QWv zHqfGFKq+m7h>#A>d=^QLn#ck}FqW#ARs@_!YT(Olc$_?P*xJuA_1oYuARe|dJCjHH zglEUsj|AJwv~p*5lLyv9E9kO6vP@#ih@BC3ez0Plb5@ZY(97em*J4?|&dzQjyAn7Y z8VF7jDzmJKmuGY$l+%SHYf!TtXeeq}uaX7U+*!Jtr!*TUlOgI4!OHaip1QN{LTT>s z3V$)qw4NhC03KS@C{Vk#RYSFQ>Bsa`7F?MI+enOgq$w8*6pHwXaOwj{d24Nd+2O{oh-6#{&YsL;W$E?GC%J?xGIY8uMs+ z9U(ZkY_1UP>bwN-8xb84&ysL`D|{CtFVmzP6UNg=D|RRsx%~_Te_Upv$_?P;FiIm#uG($0Q!%lDg|me5W`< zV{0L9x*+;(7UDFGa|sMs<-wu}!Zx#*f+WG^WBYE9Tgyb%S!Y#u7PB(QDc3{nZXA!n+}9XEVmpD zYM7A=kR~H&Y>=V)>a?Of9RJ~W1TV<|lF7}SVCN zIn>xK$nxSP1iP3l8(8PW;%>X~yxhl*dz!H6UChv~V@c^_E3{tun6Hy|W2SGC`QqMY zZzZdL7Dfw)a=RX0Ezn`^;c}BW3p?W)$k54@am-3?5nX1d?sTzSPpO|(J3-2Fai*nt zAVsAmi^3J4h_l5sVe`rC`Dq>kV&Q>-qaQP9PLO`Dm6WOzvnb0>4Jqk0v8@!*J*vLY zblnE8k>k?3$u2^Y*TxV#MxFCrr7$bRu6o|62vS(0<@;SazXS%f+}mRvA|H^Z_}&${ zSe@183Jn8;BALy(jVB(RcYBMs3vZ{;YfiV*BD|tH7yX$1xp?}#mZ|^+4{bS|SO}$d zeSZ9jaf8i|0zoVPk>Z3}AdS}R0`eefcb0q&Q$3~*3x5-1>6wS*Z-68_65x>R$pWVe~YlmA9SdI{;Dg60pf^e*->8dc}Z}u9jwrd$fHu#GoX6+%MQP6YPdlu<{ zJOQmH$j2vagO~35cIWup;-mjfU#a`vEdj^HnPb1=qfCQKZjO~d@+jGwc*HwRb^w?_7&W2Y;;Yz z&7vE_$1mXv?1VXDwr3Fl8{PxnV*_yjF2(Xe#N=*Hu$m|XJC9A`6fv?ha2BSQ(`#L+@)o2AnF6Q&2T8%%R z;?EQ|9iJmW=1&hNKR>X9OTjNit1`NZG=%?#w7-&GwgaJIXvja)K$@nz+?`LonYe%U zLyQAB@w9Ft+}fk0EwYet8!FJq(EnDy>&3GkMscgDl^Z{@qTtiL8t?-82FRdeJg z1ovIiK9E(Ruy*t)fCsfYa@Ynm5N50|U#aVmQG9`Wyk7Qy`ozBRcwF%~2&?5i+qN1k zFvlO48P1Al;WCt(^?_@P{Gjj?p$+8x5D~juQ#O4!VpGRc?wP^n*XMTm#@g`n+Q8&j z9sTt6Ewk~22JUQ?J(*uh6;`^*CaDm|5`n2NKzDCoLqnjg9GU!FjgC&Jb`dX&1xoKe zD+1IZw$uoJA;vXzb+jg-3x}{!Wz{sOC9(WBprwyAS1DuJ_0Zb+Q=HJmnkI*vkA6nX zYXb&Yw!Jef8S&d&F7UY(j!tUuk&*z8EF)(0hNvI}*cGD`HG1Rm`ZL+*GLw5WJkG_0 z=;c$S(}c}g+ z>ze$=lS*`nql{fNhxR<=F*Fg9g+IVFR@lDy^R8I1#c^BOTfGLang~M2G0r=NV63bW zS6&-BPd3X0CH0D?Wug^J&5$%wkwqI09*SfkOcNb`NIdwP#380RVq2V>dKgX?KXR;i4|-Z#mZ`J8SQIPn6uNs_kl}fO zPJgvnyk(nIwPKS9da>=;pxd-@EMly1Y5E>cZKnlFCX>&|RA^vVH!SQD?w@5wbb^0g zK0AF+_1Ji_wiaiw)EZy(kL|JQ%CqV;RS70<&EB@xh;aJ4u?i4`mg&2@SAJfI@JZD9 zh(oHt8B4X&WKf%g)B4JJbj*Z%KVHgwpD_WA^IZd9YQwcv?~`N7T1dE1ykI+}sZaL7 zXIL#Ri|B56QikOFoxBrq*wp?35f?G0vQFpru1d|E>zFkyD*bH9qt(j0O8%!?!Yuhh zlwkMg1h$RV&t&jQ8U9t#Jrpu1^!&} zQy^|w=1%#2u$6=Q4<_abG}&oWg9-sBk*2LngU6l*4%h04ELCs)#@g%Ag(gqmi@wW~ zqy`rcT(UIYbklwFf0jk}t71j2>iJ$Z&f0O6){#(?6Vp{;_Z?i)vTPh`LF131e7v}Q z<_r=}?gM#ezLT%iA)?iPj2{1voOB7B+83>@j=067z5gy4w=2XoV?j5cwac~ir4);l z-@z$rWRvQ8qaTT=1hK8o5=gFe-4iDHga`lXl390e9oeD6KAN$$F_}NSTQ{wfl5xC&5DMJ8Oy>;@RLj3-crQ|GlPc|w(hBl_sbM=<0iX1m zHgvpDx5+qBNw_eCsbd01klmKm9e0j%m{XF!bQyG(;l?BQq=3`^VzqEi;QVYv%%QOa zOD8APcW-4-X+V`U&|evMr95+^MyO(lYUYIEi)caI!y|NQGYYf=a<{~+WT7`;4ICYV#hF5p(hVj z8P!K!*Mqfb!*+`*)kUI1zSCa>wQy2;M7mWv$3h@ihqCS6Hq6VpyaV7obuS5M;1ZtE zxAap;=RmxueFOd5mp-B9h(5Mo9yeSn!VB+`^cSu#1fPmN5ktI1byLR`Ly(yHg|{Za z^IowuNSn2xVNLQ@U@}3}LY$15&*&8sCm5E5tWmT$>`F7e8KY--yj?2r<^5I+@TmP$ zTfM1}aneG!tnE8RUwL63J4iYG5E}CREFg^8iG`1~fJjo3R)j6(=~o{~Z`}=*7Y09; z-$?pwd#lfTxyl+br=wjMYH%ZIzU#+W7PFO`=&lfI7t6f~QO5Cl?@6uwiQ;B-{ma|I z+9fN;Y%6?A&pe>{nkdzQ4?kdT^p1pI2&czAQHdSBEyh;C$`&F=IN7bc zC^}1x`=^-U9oVwR$Ij;CnxhGX#k%*(ybHwD9~lDlY!=h-0Ip(AuJ7t?5YnVmLT21N-HP-B_5+MYtqYIY?^ zW{7hj8zf!{3}GG^II~YMt1)Y(O)zq+9{5i7O)S)6>CoOo=yu&gmKiy=JQT)Gx9>{c z48)V|-|fegV_*WkCSt~fMFmnCkt}(Y582I$I$0Q_-nObPKH#ofFJM(Q zc6O&XMQ>DqyT0c{s8_t>O< z>*mb9pId?|#-x3fq`uyf!by2%QW_&yC|5DpaAVhcB~)X!4!)eR%sT3JdZ89~NaNUo zi$bFN{Gq@odR73d0iu5v|EEVG*l5iA8wM9%CVTh>(0zlCJ2=*48Fk9<2_&@2re10o zGk^%`pR`$@=sATO@_XU|m86ssBJX2o$OsKA4I&LH4JHk)b;4eO(pplvsl-MY4ai?> zQZeNb)-&a)Akqnhi%Y`VLn65D4~3T!c{CvFd~`v#4KmpyGzj&JsdV2?LavXu`@S$z zCEw<}#2~?q9jEVI_Fe^z^pt>cYLo>$(h!GLL?uMzh3Utl)DKfaRm4>!ouShU2?ds_ zZM#g_!*6pTai~&nUxqpaHY#l-L0r*S4H(8*G`e-!)GO2D^Pqs3ZK)UrKZOqgk!u1x z%XrbwgdgHYdyDI)SC%|eW~VXE^2EQpwLZYTmvpM|P1f|{M{9GXOnMX4nU6HBYq!jC zQoI+(6GC97N_M(a3zie~1K2B~WD5K@hfs;CXu11~!932_!%trfpSm5}bli2WZ^%6_ zLelT@1$cyn@9c2<^!UG@GKcpJ5e^dW6u2cfAomksS)rI47lKW9wJ2{vq{hT%QZugwfdh#5UrWT`+iqh zlGof)y^_iabg`;91Qn{}%Nt@-jJDdiVxWo9qi)3tUK5zwrK5K$Fp|!#?tNWPEbW%H(Bps0V6+>yCEa)>-lcRDU?snqp`n_-OP;UIdu65m<#w^{N)yXWkjlPTE(hd6 z$Zpm_tCSoq7X%>pD5Oh`#B#JX?`S)q0X1vrmvYy6{`BgX+fUz!7xQ-f6Q~uB2h{By zZ|`o2f=Mu*b1&0unXWN@nDVWYH>ulymyhNlP=iP**rx8GG%j_5&JfjO1OtPW`}11> z01>v*(rHz39d6Y6Q_V^I0xdjX=(Fvo7UEd_uq$%_uUW%R;^=~`kF&bD`C@n+`>!xs zbH<1z?)MtFCpH=H^gtRp7|O{d-IVH~%9-9VkL;N`{Ke{(xI&0=L2l_^1;>YuW5;+a0-{rgc_> z-d3Va^uB-OP}X+ggA^qpt;GSjql*wih2+SaVl(VO&Uc*UrV0=whXE*%u$zy4G0g>S z;Frf_|390@#;}fajR_yqLT=q3PnUQGDl>W}j!LAp%V5)LA>WO|`qSMDKXl zyfmS5daX&PJ4GA+@A{ou31zh388Oq9LI`l9m2{8cB^Gi8M%4?TYW zWA%zAC9|M#{p0p;9%OOM2M*tfJ?!7Tapu9stTnUFo?{FvjutZY1FdMeWl^ZSq$THy zUzEjf@Ady8fdkRsTQ_&}-qk*)HD9)fNo3<%#rMepcdJ=N`_FM#u=_x8Kn zu9|h9ePfk-u*qHOBTHD-8PIYOx0*MMb+27{($?GN-)pWrebs3H%bL}x^L=k`d+aN; zY1xO6J{F1d-%D?t+u)rzkxS93URv`nSMyQd?F)V9SW7$K-u=MpShdJKzG%T1;oivN z6)kJNzFPfT`NgV}-&byc^f9V?LbW#3Jw3Je;uV+sXCYk--k*BmrD~z!`ZNI2_cpai*wUzv$|7Uu0Z>Q?w;(M4Mxmb`|73>0K-I+A1?m;PDUU zp3}+~nX3)g@GldQW!mH9dA>5@GF!=;m>b_V6es8(dZl|%KV7$JFYC8riTm2D4hkVo z*G%FJ#SY#$!*DLub=46|gIyQBKW-E~DDR_cxb}r0&y8KHrcST^&uA^X&Gb$4hS!Oj zGlEPwYeetX**=L~?*7f%pz6&O`N`MJIwF@ z;Cq*6&a-E^>F0Vva?&D}_guay>D=>4vF>-f_jTvBmzTM|I>vwb=d;Xz#12(_K5Mq2{NTEVi_yzOYMFSLBLyZVeqg^mAGixKzbTO6 zpX9OQ+uc+RzfIjEX?8H;Ms=cBr~(78P~VmnD>L_}SXJ)7fA7Y&ttoYvEYAQJNXz>^ z`1I`A&Xrdtyr2E7fbZRL%MX8*Q%d+(Z9iVJFLZtT)J)F$2e!d>UnXiEkFVcrlRee( z)zw40*OfP)J-J!-gPqCz)i1a&GrUQ>5p;w3X85sJuCYDI9InFp(eV*qR{U(VU-W|g zOn3NRmARoMU*1G6oMzuwRTsN(*Qu3l-lZSe#r8ke*_hHHFV}? zZK-Q{%e?*KkL*3b&HP_o6PVf#dw>2?aH(kf&pNgo?Fj2N%D=OIS=zLGlJ>q)Y~l9t zl>H`3 z;9dHq&JFVqezB@tG)=qhgZIp7CvGlFU(5cCGd%9!b>4`E1y??>{Mf!pJ4dZ2k#pxa zw>{6V3jaHBW^3A>=l$0Id@t_m&iOC>+xFtAtL#(YM@)bi3zo4wIkH-_&QuR^J_F)d o0{B@Wqm0oIpezJ>y&n8$zN{O##54O!1?cE8Pgg&ebxsLQ0E_IebN~PV literal 0 HcmV?d00001 diff --git a/mkdocs.yml b/mkdocs.yml index 65f7992..e862607 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,6 +24,7 @@ pages: - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' - 'Updating': 'main/update.md' +- 'FTLDNS': "ftldns/index.md" - 'Guides': - 'Pi-hole and OpenVPN Server': - 'Overview': 'guides/vpn/overview.md' From d2687cb34f4ee1f415ba1087cc0ff3fa106e2108 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Tue, 1 May 2018 22:26:09 +0200 Subject: [PATCH 2/6] Use asset image Signed-off-by: DL6ER --- docs/ftldns/index.md | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/ftldns/index.md b/docs/ftldns/index.md index 9a18ec0..7af0648 100644 --- a/docs/ftldns/index.md +++ b/docs/ftldns/index.md @@ -1,7 +1,5 @@ -

-FTLDNS
-

+

FTLDNS
powered by Pi-hole®

*FTL*DNS[™](https://pi-hole.net/trademark-rules-and-brand-guidelines/) (`pihole-FTL`) offers DNS services within the Pi-hole[®](https://pi-hole.net/trademark-rules-and-brand-guidelines/) project. -It provides DNS and DHCP services (it can also provide TFTP and more) as well as an interactive API where generated statistics for 's Web interface can be queried. The internal DNS server is based on the popular `dnsmasq`. +It provides blazing fast DNS and DHCP services. It can also provide TFTP and more as the resolver part based on the popular `dnsmasq`. Furthermore, FTL offers an interactive API where extensive network analysis data and statistics may be queried. From ed1a6914a78d9f648a2d0af7477a700cb2159d98 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Thu, 3 May 2018 20:45:41 +0200 Subject: [PATCH 3/6] Add linux capabilites section Signed-off-by: DL6ER --- docs/extra.css | 5 +++-- docs/ftldns/in-depth.md | 14 ++++++++++++++ mkdocs.yml | 4 +++- 3 files changed, 20 insertions(+), 3 deletions(-) create mode 100644 docs/ftldns/in-depth.md diff --git a/docs/extra.css b/docs/extra.css index ebe9442..8b0999f 100644 --- a/docs/extra.css +++ b/docs/extra.css @@ -11,7 +11,8 @@ body, input { font-family: "Source Sans Pro", "Roboto","Helvetica Neue",Helvetica,Arial,sans-serif; color: black; } -code { +.md-typeset code, .md-typeset pre { display: inline-block; white-space: pre-wrap; -} \ No newline at end of file + color: rgb(83, 43, 168); +} diff --git a/docs/ftldns/in-depth.md b/docs/ftldns/in-depth.md new file mode 100644 index 0000000..3d29282 --- /dev/null +++ b/docs/ftldns/in-depth.md @@ -0,0 +1,14 @@ +## Linux capabilites +Capabilities (POSIX 1003.1e, [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html)) provide fine-grained control over superuser permissions, allowing use of the `root` user to be avoided. +For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: *privileged processes* (superuser or `root`), and *unprivileged processes*. Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (user and grounp permissions and supplementary process capabilities). Capabilities are implemented on Linux using extended attributes ([xattr(7)](http://man7.org/linux/man-pages/man5/attr.5.html)) in the `security` namespace. Extended attributes are supported by all major Linux file systems, including Ext2, Ext3, Ext4, Btrfs, JFS, XFS, and Reiserfs. + +For your safety and comfort, `pihole-FTL` is run by the entirely unpriviledged user `pihole`. +Wheras `dnsmasq` is running as `root` process, we designed `pihole-FTL` to be run by the entirely unpriviledged user `pihole`. As a consequence, `pihole-FTL` will not be able to access the files of any other user on this system or mess around with your system's configuration. + +However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among some other necessary capabilites related to DHCP services. To establish a strong security model, we explicitly grant the `pihole-FTL` process additional capabilities so that `pihole-FTL` (but no other processes which may be started by `pihole`) can bind to port 53, etc., without giving any additional permissions to the `pihole` user. + +We specifically add the following capabilities to `pihole-FTL`: + +- `CAP_NET_BIND_SERVICE`: Allows *FTl*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) +- `CAP_NET_RAW`: use RAW and PACKET sockets (we need a RAW socket for handling DHCPv6 requests) +- `CAP_NET_ADMIN`: modify routing tables and other network-related operations (to allow for handling DHCP requests) diff --git a/mkdocs.yml b/mkdocs.yml index e862607..fca4da9 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -24,7 +24,9 @@ pages: - 'Installation': 'main/basic-install.md' - 'Post-Install': 'main/post-install.md' - 'Updating': 'main/update.md' -- 'FTLDNS': "ftldns/index.md" +- 'FTLDNS': + - 'Overview': "ftldns/index.md" + - 'In-depth manual': "ftldns/in-depth.md" - 'Guides': - 'Pi-hole and OpenVPN Server': - 'Overview': 'guides/vpn/overview.md' From 592d362c065cc885671e7068655a9847d83048f9 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Thu, 3 May 2018 22:42:28 +0200 Subject: [PATCH 4/6] Add regex description Signed-off-by: DL6ER --- docs/ftldns/in-depth.md | 2 +- docs/ftldns/regex.md | 53 +++++++++++++++++++++++++++++++++++++++++ mkdocs.yml | 1 + 3 files changed, 55 insertions(+), 1 deletion(-) create mode 100644 docs/ftldns/regex.md diff --git a/docs/ftldns/in-depth.md b/docs/ftldns/in-depth.md index 3d29282..a6d0f49 100644 --- a/docs/ftldns/in-depth.md +++ b/docs/ftldns/in-depth.md @@ -9,6 +9,6 @@ However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among som We specifically add the following capabilities to `pihole-FTL`: -- `CAP_NET_BIND_SERVICE`: Allows *FTl*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) +- `CAP_NET_BIND_SERVICE`: Allows *FTL*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) - `CAP_NET_RAW`: use RAW and PACKET sockets (we need a RAW socket for handling DHCPv6 requests) - `CAP_NET_ADMIN`: modify routing tables and other network-related operations (to allow for handling DHCP requests) diff --git a/docs/ftldns/regex.md b/docs/ftldns/regex.md new file mode 100644 index 0000000..b2fd6f9 --- /dev/null +++ b/docs/ftldns/regex.md @@ -0,0 +1,53 @@ +A regular expression, or regex for short, is a pattern that can be used for building arbitrarily complex blocking rules in *FTL*DNS. +We implement the Extended Regular Expressions flavor similar to the one used by the UNIX `egrep` (or `grep -E`) command. + +Obviously, this brief description cannot explain everything there is to know about regular expressions. For detailed information, consult one of the excelent regular expressions tutorial that are available online. + +## Language implementation +We provide a short cheat sheet for our regular expressions implementation that may come in handy when designing blocking rules. Note that this table is not complete and will be extended over time. + +### Character classes +Expression | Meaning | Example +------------ | ------------- | ----------- +`*` | Match zero, one or more of the previous | Ah* matches "Ahhhhh" or "A" +`?` | Match zero or one of the previous | Ah? matches "Al" or "Ah" +`+` | Match one or more of the previous | Ah+ matches "Ah" or "Ahhh" but not "A" +`\` | Used to escape a special character | Hungry\? matches "Hungry?" +`.` | Wildcard character, matches any character | `do.*` matches "do", dog", "door", "dot", etc. +| | `do.+` matches "dog", "door", "dot", etc. but not "do" (at wildcard with `+` requires to match at least one extra character) +`( )` | Group | See below example for alternation (`|`) +`|` | Alternation | `(Mon|Tues)day` matches "Monday" or "Tuesday" but not "Friday" or "Mond" +`[ ]` | Matches a range of characters | `[cbf]ar` matches "car", "bar", or "far" +| | `[0-9]+` matches any positive integer +| | `[a-zA-Z]` | matches ascii letters a-z (uppercase and lower case) +| | `[^0-9]` | matches any character not 0-9. +`{ }` | Matches a specified number of occurrences of the previous | `[0-9]{3}` matches any three-digit number like "315" but not "31" +| | `[0-9]{2,4}` matches two- to four-digit numbers like "12", "123", and "1234" but not "1" or "12345" +| | `[0-9]{2,}` matches any number with two or more digits like "1234567", "123456789", but not "1" +`^` | Beginning of string | `^client` matches strings that begin with "client", such as `client.server.com` but not `more.client.server.com` +| Exception: within a character range (`[]`) `^` means negation | `[^0-9]` matches any character not 0-9. +`$` | End of string | `ing$` matches "exciting" but not "ingenious" + + +### Example +We compiled an example to demonstrate the power of regex-based blocking: + +Consider the following regex: +``` +^ab.+\.com$ +``` +This pattern will block all domains that start with "ab" (`^ab`), have at least one further character (`.+`) and end in ".com" (`\.com$`). + +Examples for what would be blocked by this rule: + + - `abc.com` + - `abtest.com` + - `ab.test.com` + - `abr-------.whatever.com` + +Examples for what would not be blocked by this rule: + + - `testab.com` (the domain doesn't start with "ab") + - `tab.test.com` (the domain doesn't start with "ab") + - `ab.com` (there is no character in between "ab" and ".com") + - `test.com.something` (the domain doesn't end in ".com") diff --git a/mkdocs.yml b/mkdocs.yml index fca4da9..62acee5 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,6 +26,7 @@ pages: - 'Updating': 'main/update.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" + - 'RegEx blocking': "ftldns/regex.md" - 'In-depth manual': "ftldns/in-depth.md" - 'Guides': - 'Pi-hole and OpenVPN Server': From 2fdfeda9db09cdf4d7b650858c7bcdc9c19026ce Mon Sep 17 00:00:00 2001 From: DL6ER Date: Fri, 4 May 2018 18:36:59 +0200 Subject: [PATCH 5/6] Updated RegEx page (added a full tutorial for our RegEx flavor) + describe the BLOCKINGMODEs available + write some lines about the lists format Signed-off-by: DL6ER --- README.md | 2 +- docs/ftldns/blockingmode.md | 44 +++++++++ docs/ftldns/in-depth.md | 15 ++- docs/ftldns/regex.md | 178 ++++++++++++++++++++++++++---------- mkdocs.yml | 5 + 5 files changed, 190 insertions(+), 54 deletions(-) create mode 100644 docs/ftldns/blockingmode.md diff --git a/README.md b/README.md index 160f3b5..8531803 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ git clone git@github.com:pi-hole/docs.git cd docs sudo pip install mkdocs sudo pip install mkdocs-material -mkdocs serve +mkdocs serve --dev-addr 0.0.0.0:8000 ``` Deploying to GitHub pages: diff --git a/docs/ftldns/blockingmode.md b/docs/ftldns/blockingmode.md new file mode 100644 index 0000000..244f5ac --- /dev/null +++ b/docs/ftldns/blockingmode.md @@ -0,0 +1,44 @@ +Pi-hole *FTL*DNS supports two different methods for blocking queries. Both have their advantages and drawbacks. They are summarized on this page. The blocking mode can be configured in `/etc/pihole/pihole-FTL.conf`. + +## Pi-hole's IP based blocking +`/etc/pihole/pihole-FTL.conf` setting: +``` +BLOCKINGMODE=IP +``` + +Queries will be answered with the local IP addresses of your Pi-hole (as configured in your `setupVars.conf` file) +``` +;; QUESTION SECTION: +;doubleclick.net. IN ANY + +;; ANSWER SECTION: +doubleclick.net. 2 IN A 192.168.2.11 +doubleclick.net. 2 IN AAAA fda2:2001:4756:0:ab27:beff:ef37:4242 +``` + +##### Advantage +- Shows blocking page from which blocked webpages can be whitelisted + +##### Disadvantages +- Requires a webserver to run on your Pi-hole +- May cause time-outs for HTTPS content even with properly configured firewall rules + +## Pi-hole's NXDOMAIN based blocking +`/etc/pihole/pihole-FTL.conf` setting: +``` +BLOCKINGMODE=NXDOMAIN +``` +Queries DNS queries will be answered with an empty response (no answer section) and status `NXDOMAIN` (*no such domain*) +``` +;; QUESTION SECTION: +;doubleclick.net. IN ANY +``` + +##### Advantages +- The client does not even try to establish a connection for the requested website +- Speedup and less traffic +- Solves potential HTTPS timeouts as requests are never performed +- No need to run a webserver on your Pi-hole (reduces complexity when running other web services on the same machine) + +##### Disadvantage +- Blocking page cannot be shown and whitelisting has to be performed from the dashboard or CLI diff --git a/docs/ftldns/in-depth.md b/docs/ftldns/in-depth.md index a6d0f49..a54e894 100644 --- a/docs/ftldns/in-depth.md +++ b/docs/ftldns/in-depth.md @@ -1,14 +1,19 @@ -## Linux capabilites +## Domain lists format +Since Pi-hole v4.0, we use a simpler domain list format for the two important block list files `gravity.list` and `black.list`. In contrast to the traditional HOSTS format (which caused a lot of overhead), the domain list format is the minimal possible solution for saving memory while still using plain text lists for your convenience. When *FTL*DNS imports these two files, they are walked by our improved list parser speeding up the loading of block lists significantly. Regardless which blocking mode (`IP` or `NXDOMAIN`) is selected, *FTL*DNS will always load the lists into it's internal hashed cache to be able to determine the blocking status within a few milliseconds, even when you're using huge blocking lists on low-end devices. With everything we do, we design *FTL*DNS for maximum efficiency also on low-performance devices. + +## Linux capabilities Capabilities (POSIX 1003.1e, [capabilities(7)](http://man7.org/linux/man-pages/man7/capabilities.7.html)) provide fine-grained control over superuser permissions, allowing use of the `root` user to be avoided. -For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: *privileged processes* (superuser or `root`), and *unprivileged processes*. Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (user and grounp permissions and supplementary process capabilities). Capabilities are implemented on Linux using extended attributes ([xattr(7)](http://man7.org/linux/man-pages/man5/attr.5.html)) in the `security` namespace. Extended attributes are supported by all major Linux file systems, including Ext2, Ext3, Ext4, Btrfs, JFS, XFS, and Reiserfs. +For the purpose of performing permission checks, traditional UNIX implementations distinguish two categories of processes: *privileged processes* (superuser or `root`), and *unprivileged processes*. Privileged processes bypass all kernel permission checks, while unprivileged processes are subject to full permission checking based on the process's credentials (user and group permissions and supplementary process capabilities). Capabilities are implemented on Linux using extended attributes ([xattr(7)](http://man7.org/linux/man-pages/man5/attr.5.html)) in the `security` namespace. Extended attributes are supported by all major Linux file systems, including Ext2, Ext3, Ext4, Btrfs, JFS, XFS, and ReiserFS. -For your safety and comfort, `pihole-FTL` is run by the entirely unpriviledged user `pihole`. -Wheras `dnsmasq` is running as `root` process, we designed `pihole-FTL` to be run by the entirely unpriviledged user `pihole`. As a consequence, `pihole-FTL` will not be able to access the files of any other user on this system or mess around with your system's configuration. +For your safety and comfort, `pihole-FTL` is run by the entirely unprivileged user `pihole`. +Whereas `dnsmasq` is running as `root` process, we designed `pihole-FTL` to be run by the entirely unprivileged user `pihole`. As a consequence, `pihole-FTL` will not be able to access the files of any other user on this system or mess around with your system's configuration. -However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among some other necessary capabilites related to DHCP services. To establish a strong security model, we explicitly grant the `pihole-FTL` process additional capabilities so that `pihole-FTL` (but no other processes which may be started by `pihole`) can bind to port 53, etc., without giving any additional permissions to the `pihole` user. +However, this also implies that *FTL*DNS cannot bind to ports 53 (DNS) among some other necessary capabilities related to DHCP services. To establish a strong security model, we explicitly grant the `pihole-FTL` process additional capabilities so that `pihole-FTL` (but no other processes which may be started by `pihole`) can bind to port 53, etc., without giving any additional permissions to the `pihole` user. We specifically add the following capabilities to `pihole-FTL`: - `CAP_NET_BIND_SERVICE`: Allows *FTL*DNS binding to TCP/UDP sockets below 1024 (specifically DNS service on port 53) - `CAP_NET_RAW`: use RAW and PACKET sockets (we need a RAW socket for handling DHCPv6 requests) - `CAP_NET_ADMIN`: modify routing tables and other network-related operations (to allow for handling DHCP requests) + +Users that cannot use Linux capabilites for various reasons (lacking kernel or file system support) can modify the startup scripts of `pihole-FTL` to ensure the daemon is started as `root`. However, be aware of that you do so on your own risk (although we don't expect problems to arise). diff --git a/docs/ftldns/regex.md b/docs/ftldns/regex.md index b2fd6f9..0a39a6f 100644 --- a/docs/ftldns/regex.md +++ b/docs/ftldns/regex.md @@ -1,53 +1,135 @@ -A regular expression, or regex for short, is a pattern that can be used for building arbitrarily complex blocking rules in *FTL*DNS. -We implement the Extended Regular Expressions flavor similar to the one used by the UNIX `egrep` (or `grep -E`) command. +A regular expression, or RegEx for short, is a pattern that can be used for building arbitrarily complex blocking rules in *FTL*DNS. +We implement the Extended Regular Expressions (ERE) flavor similar to the one used by the UNIX `egrep` (or `grep -E`) command. -Obviously, this brief description cannot explain everything there is to know about regular expressions. For detailed information, consult one of the excelent regular expressions tutorial that are available online. +Our implementation is computationally inexpensive as each domain is only checked once for a match (if you query `google.com`, it will be checked against your RegEx. Any subsequent query to the same domain will not be checked again until you restart `pihole-FTL`). -## Language implementation -We provide a short cheat sheet for our regular expressions implementation that may come in handy when designing blocking rules. Note that this table is not complete and will be extended over time. +## How to use regular expressions for blocking +Add a line +``` +BLOCKINGREGEX=^abc$ +``` +in your `/etc/pihole/pihole-FTL.conf` and restart `pihole-FTL`. **Note: this is subject to change (we plan to support a list of regular expressions for blocking in the near future).** + +## Pi-hole regular expressions tutorial +We provide a short but thorough introduction to our regular expressions implementation. This may come in handy if you are designing blocking rules (see also our cheat sheet below!). In our implementation, all characters match themselves except for the following special characters: `.[{}()\*+?|^$`. If you want to match those, you need to escape them like `\.` for a literal period, but no rule without exception (see character groups below for further details). + +### Anchors (`^` and `$`) +First of all, we look at anchors which can be used to indicate the start or the end of a domain, respectively. If you don't specify anchors, the match may be partial (see examples below). + +Example | Interpretation +--- | --- +`domain` | **partial match**. Without anchors, a text may appear anywhere in the domain. This matches `some.domain.com`, `domain.com` and `verylongdomain.com` and more +`^localhost$` | **exact match** matching *only* `localhost` but neither `a.localhost` nor `localhost.com` +`^abc` | matches any domain **starting** (`^`) in "abc" like `abcdomain.com`, `abc.domain.com` but not `def.abc.com` +`com$` | matches any domain **ending** (`$`) in "com" such as `domain.com` but not `domain.com.co.uk` + +### Wildcard (`.`) +An unescaped period stands for any *single* character. + +Example | Interpretation +--- | --- +`^domain.$` | matches `domaina`, `domainb`, `domainc`, but not `domain` + +### Bounds and multipliers (`{}`, `*`, `+`, and `?`) +With bounds, one can denote the number of times something has to occur: + +Bound | Meaning +--- | --- +`ab{4}` | matches a domain that contains a single `a` followed by four `b` (matching only `abbbb`) +`ab{4,}` | matches a domain that contains a single `a` followed by *at least* four `b` (matching also `abbbbbbbb`) +`ab{3,5}` | matches a domain that contains a single `a` followed by three to five `b` (matching only `abbb`, `abbbb`, and `abbbbb`) + +Multipliers are shortcuts for some of the bounds that are needed most often: + +Multipliers | Bounds equivalent | Meaning +--- | --- | --- +`?` | `{0,1}` | never or once (optional) +`*` | `{0,}` | never or more (optional) +`+` | `{1,}` | once or more (mandatory) + +To illustrate the usefulness of multipliers (and bounds), we provide a few examples: + +Example | Interpretation +--- | --- +`^r-*\.movie` | matches a domain like `r------movie.com` where the number of dashes can be arbitrary (also none) +`^r-?\.movie` | matches only the domains `rmovie.com` and `r-movie.com` but not those with more than one dash +`^r-+\.movie` | matches only the domains with at least one dash, i.e., not `rmovie.com` +`^a?b+` | matches domains like `abbbb.com` (zero or one `a` at the beginning followed by one or more `b`) + +### Character groups (`[]`) +With character groups, a set of characters can be matched: + +Character group | Interpretation +--- | --- +`[abc]` | matches `a`, `b`, or `c` (using explicitly specified characters) +`[a-c]` | matches `a`, `b`, or `c` (using a *range*) +`[a-c]?` | matches any number of `a`, `b`, `c` +`[a-c]*` | as `[a-c]*` but optional +`[a-z]` | matches any single lowercase letter +`[a-zA-Z]` | matches any single letter +`[a-z0-9]` | matches any single lowercase letter or any single digit +`[^a-z]` | **Negation** matching any single character *except* lowercase letters +`abc[0-9]+` | matches the string `abc` followed by a number of arbitrary length + +Bracket expressions are an exception to the character escape rule. Inside them, all special characters, including the backslash (`\`), lose their special powers, i.e. they match themselves exactly. Furthermore, to include a literal `]` in the list, make it the first character (like `[]]` or `[^]]` if negated). To include a literal `-`, make it the first or last character, or the second endpoint of a range (e.g. `[a-z-]` to match `a` to `z` and `-`). + +### Groups (`()`) +Using groups, we can enclose regular expressions, they are most powerful when combined with bounds or multipliers (see also alternations below). + +Example | Interpretation +--- | --- +`(abc)` | matches `abc` (trivial example) +`(abc)*` | matches zero or more copies of `abc` like `abcabc` but not `abcdefabc` +`(abc){1,3}` | matches one, two or three copies of `abc`: `abc`, `abcabc`, `abcabcabc` but nothing else + +### Alternations (`|`) +Alternations can be used as an "or" operator in regular expressions. + +Example | Interpretation +--- | --- +`(abc)|(def)` | matches `abc` *and* `def` +`domain(a|b)\.com` | matches `domaina.com` and `domainb.com` but not `domain.com` or `domainx.com` +`domain(a|b)*\.com` | matches `domain.com`, `domainaaaa.com` `domainbbb.com` but not `domainab.com` (any number of `a` or `b` in between `domain` and `.com`) + +### Character classes (`[:class:]`) +In addition to character groups, there are also some special character classes available, such as + +Character class | Group equivalent | Interpretation +--- | --- | --- +`[:digit:]` | `[0-9]` | matches digits +`[:lower:]` | `[a-z]` | matched lowercase letters +`[:upper:]` | `[A-Z]` | matched uppercase letters +`[:alpha:]` | `[A-Za-z]` | matches alphabetic characters +`[:alnum:]` | `[A-Za-z0-9]` | matches alphabetic characters and digits + +## Advanced examples +After going through our quick tutorial, we provide some more advances examples so you can test your knowledge. + +### Block domain with only numbers +``` +^[0-9][^a-z]+\.((com)|(edu))$ +``` +Blocks domains containing only numbers (no letters) and ending in `.com` or `.edu`. Blocks `555661.com`, and `456.edu`, but not `555g555.com` + +### Block domains without subdomains +``` +^[a-z0-9]+([\-]{1}[a-z0-9]+)*\.[a-z]{2,7}$ +``` +A domain name shall not start or end with a dash but can contain any number of them. It must be followed by a TLD (we assume a valid TLD length of two to seven characters) + +## Cheatsheet -### Character classes Expression | Meaning | Example ------------ | ------------- | ----------- -`*` | Match zero, one or more of the previous | Ah* matches "Ahhhhh" or "A" -`?` | Match zero or one of the previous | Ah? matches "Al" or "Ah" -`+` | Match one or more of the previous | Ah+ matches "Ah" or "Ahhh" but not "A" -`\` | Used to escape a special character | Hungry\? matches "Hungry?" -`.` | Wildcard character, matches any character | `do.*` matches "do", dog", "door", "dot", etc. -| | `do.+` matches "dog", "door", "dot", etc. but not "do" (at wildcard with `+` requires to match at least one extra character) -`( )` | Group | See below example for alternation (`|`) -`|` | Alternation | `(Mon|Tues)day` matches "Monday" or "Tuesday" but not "Friday" or "Mond" -`[ ]` | Matches a range of characters | `[cbf]ar` matches "car", "bar", or "far" -| | `[0-9]+` matches any positive integer -| | `[a-zA-Z]` | matches ascii letters a-z (uppercase and lower case) -| | `[^0-9]` | matches any character not 0-9. -`{ }` | Matches a specified number of occurrences of the previous | `[0-9]{3}` matches any three-digit number like "315" but not "31" -| | `[0-9]{2,4}` matches two- to four-digit numbers like "12", "123", and "1234" but not "1" or "12345" -| | `[0-9]{2,}` matches any number with two or more digits like "1234567", "123456789", but not "1" -`^` | Beginning of string | `^client` matches strings that begin with "client", such as `client.server.com` but not `more.client.server.com` -| Exception: within a character range (`[]`) `^` means negation | `[^0-9]` matches any character not 0-9. -`$` | End of string | `ing$` matches "exciting" but not "ingenious" - - -### Example -We compiled an example to demonstrate the power of regex-based blocking: - -Consider the following regex: -``` -^ab.+\.com$ -``` -This pattern will block all domains that start with "ab" (`^ab`), have at least one further character (`.+`) and end in ".com" (`\.com$`). - -Examples for what would be blocked by this rule: - - - `abc.com` - - `abtest.com` - - `ab.test.com` - - `abr-------.whatever.com` - -Examples for what would not be blocked by this rule: - - - `testab.com` (the domain doesn't start with "ab") - - `tab.test.com` (the domain doesn't start with "ab") - - `ab.com` (there is no character in between "ab" and ".com") - - `test.com.something` (the domain doesn't end in ".com") +`^` | Beginning of string | `^client` matches strings that begin with `client`, such as `client.server.com` but not `more.client.server.com` (exception: within a character range (`[]`) `^` means negation) +`$` | End of string | `ing$` matches `exciting` but not `ingenious` +`*` | Match zero or more of the previous | `ah*` matches `ahhhhh` or `a` +`?` | Match zero or one of the previous | `ah?` matches `a` or `ah` +`+` | Match one or more of the previous | `ah+` matches `ah` or `ahhh` but not `a` +`.` | Wildcard character, matches any character | `do.*` matches `do`, `dog`, `door`, `dot`, etc.;
`do.+` matches `dog`, `door`, `dot`, etc. but not `do` (wildcard with `+` requires at least one extra character for matching) +`( )` | Group | Enclose regular expressions, see the example for `|` +`|` | Alternation | `(mon|tues)day` matches `monday` or `tuesday` but not `friday` or `mondiag` +`[ ]` | Matches a range of characters | `[cbf]ar` matches `car`, `bar`, or `far`; +`[^]`| Negation | `[^0-9]` matches any character *except* `0` to `9` +`{ }` | Matches a specified number of occurrences of the previous | `[0-9]{3}` matches any three-digit number like `315` but not `31`;
`[0-9]{2,4}` matches two- to four-digit numbers like `12`, `123`, and `1234` but not `1` or `12345`;
`[0-9]{2,}` matches any number with two or more digits like `1234567`, `123456789`, but not `1` +`\` | Used to escape a special character not inside `[]` | `google\.com` matches `google.com` diff --git a/mkdocs.yml b/mkdocs.yml index 62acee5..dbabb98 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -26,9 +26,14 @@ pages: - 'Updating': 'main/update.md' - 'FTLDNS': - 'Overview': "ftldns/index.md" + - 'Blocking mode': "ftldns/blockingmode.md" - 'RegEx blocking': "ftldns/regex.md" +# - 'Privacy levels': "ftldns/privacy.md" +# - 'Long-term database': "ftldns/database.md" +# - 'API documentation': "ftldns/api.md" - 'In-depth manual': "ftldns/in-depth.md" - 'Guides': +# - 'Pi-hole as All-Around DNS Solution': guides/unbound.md - 'Pi-hole and OpenVPN Server': - 'Overview': 'guides/vpn/overview.md' - 'Installation': 'guides/vpn/installation.md' From ac27a22f59a5524cc34fdcc396cb946b3b53a931 Mon Sep 17 00:00:00 2001 From: DL6ER Date: Fri, 4 May 2018 22:10:27 +0200 Subject: [PATCH 6/6] Fix character groups description for [a-c]* Signed-off-by: DL6ER --- docs/ftldns/regex.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/docs/ftldns/regex.md b/docs/ftldns/regex.md index 0a39a6f..8b7ac78 100644 --- a/docs/ftldns/regex.md +++ b/docs/ftldns/regex.md @@ -63,8 +63,7 @@ Character group | Interpretation --- | --- `[abc]` | matches `a`, `b`, or `c` (using explicitly specified characters) `[a-c]` | matches `a`, `b`, or `c` (using a *range*) -`[a-c]?` | matches any number of `a`, `b`, `c` -`[a-c]*` | as `[a-c]*` but optional +`[a-c]+` | matches any non-zero number of `a`, `b`, `c` `[a-z]` | matches any single lowercase letter `[a-zA-Z]` | matches any single letter `[a-z0-9]` | matches any single lowercase letter or any single digit