From 484aa07381c8f9eb8ea3f5e70a43b0b520948907 Mon Sep 17 00:00:00 2001 From: Kevin Fronczak Date: Mon, 23 Oct 2017 03:24:36 -0400 Subject: [PATCH] Fail2Ban Sensor Documentation (#3679) * Initial revision of sensor.fail2ban docs * Bumped version --- source/_components/sensor.fail2ban.markdown | 185 ++++++++++++++++++++ source/images/supported_brands/fail2ban.png | Bin 0 -> 17857 bytes 2 files changed, 185 insertions(+) create mode 100644 source/_components/sensor.fail2ban.markdown create mode 100644 source/images/supported_brands/fail2ban.png diff --git a/source/_components/sensor.fail2ban.markdown b/source/_components/sensor.fail2ban.markdown new file mode 100644 index 00000000000..c96b3109910 --- /dev/null +++ b/source/_components/sensor.fail2ban.markdown @@ -0,0 +1,185 @@ +--- +layout: page +title: "Fail2Ban Sensor" +description: "Instructions how to integrate a fail2ban sensor into Home Assistant." +date: 2017-10-19 10:30 +sidebar: true +comments: false +sharing: true +footer: true +ha_category: Sensor +ha_iot_class: "Local Polling" +logo: fail2ban.png +ha_release: 0.57 +--- + + +The `fail2ban` sensor allows for IPs banned by [fail2ban](https://www.fail2ban.org/wiki/index.php/Main_Page) to be displayed in the Home Assistant front-end. + +

+Your system must have fail2ban installed and correctly configured for this sensor to work. In addition, Home Assistant must be able to read the fail2ban log file. +

+ +To enable this sensor, add the following lines to your `configuration.yaml`: + +```yaml +# Example configuration.yaml entry +sensor: + - platform: fail2ban + jails: + - ssh + - hass-iptables + file_path: /var/log/fail2ban.log +``` + +Configuration variables: + +- **jails** (*Required*): List of configured jails you want to display (each jail is its own sensor). +- **name** (*Optional*): Name of the sensor. Defaults to `fail2ban`. +- **file_path** (*Optional*): Path to the fail2ban log. Defaults to `/var/log/fail2ban.log`. +- **scan_interval** (*Optional*): Used to limit how often log file is read and must be a positive integer (representing number of seconds to wait). Defaults to 120. + +### {% linkable_title Set up Fail2Ban %} + +For most set-ups, you can follow [this tutorial](https://home-assistant.io/cookbook/fail2ban/) to set up fail2ban on your system. It will walk you through creating jails and filters, allowing you to monitor IPs that have been banned for too many failed ssh login attempts, as well as too many failed Home Assistant log in attempts. + +### {% linkable_title Fail2Ban with Docker %} + +

+These steps assume you already have the Home Assistant docker running behind nginx and that it is externally accessible. It also assumes the docker is running with the `--net='host'` flag. +

+ +For those of us using Docker, the above tutorial may not be sufficient. The following steps specifically outline how to set up `fail2ban` and Home Assistant when running Home Assistant within a Docker behind nginx. The setup this was tested on was an unRAID server using the [let's encrypt docker](https://github.com/linuxserver/docker-letsencrypt) from linuxserver.io. + +#### Set http logger + +In your `configuration.yaml` file, add the following to the `logger` component to ensure that Home Assistant prints failed login attempts to the log. + +```yaml +logger: + logs: + homeassistant.components.http.ban: warning +``` + +#### Edit the `jail.local` file + +Next, we need to edit the `jail.local` file that is included with the Let's Encrypt docker linked above. Note, for this tutorial, we'll only be implementing the `[hass-iptables]` jail from the [previously linked tutorial](https://home-assistant.io/cookbook/fail2ban/). + +Edit `/mnt/user/appdata/letsencrypt/fail2ban/jail.local` and append the following to the end of the file: + +``` +[hass-iptables] +enabled = true +filter = hass +action = iptables-allports[name=HASS] +logpath = /hass/home-assistant.log +maxretry = 5 +``` + +#### Create a filter for the Home Assistant jail + +Now we need to create a filter for `fail2ban` so that it can properly parse the log. This is done with a `failregex`. Create a file called `hass.local` within the `filter.d` directory in `/mnt/user/appdata/letsencrypt/fail2ban` and add the following: + +``` +[INCLUDES] +before = common.conf + +[Definition] +failregex = ^%(__prefix_line)s.*Login attempt or request with invalid authentication from .*$ + +ignoreregex = + +[Init] +datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S +``` + +#### Map log file directories + +First, we need to make sure that fail2ban log can be passed to Home Assistant and that the Home Assistant log can be passed to fail2ban. When starting the Let's Encrypt docker, you need to add the following argument (adjust paths based on your setup): + +``` +/mnt/user/appdata/home-assistant:/hass +``` + +This will map the Home Assistant configuration directory to the Let's Encrypt docker, allowing `fail2ban` to parse the log for failed login attempts. + +Now do the same for the Home Assistant docker, but this time we'll be mapping the `fail2ban` log directory to Home Assistant so that the fail2ban sensor is able to read that log: + +``` +/mnt/user/appdata/letsencrypt/log/fail2ban:/fail2ban +``` + + +#### Send client IP to Home Assistant + +By default, the IP address that Home Assistant sees will be that of the container (something like `172.17.0.16`). What this means is that for any failed login attempt, assuming you have correctly configured `fail2ban`, the Docker IP will be logged as banned, but the originating IP is still allowed to make attempts. We need `fail2ban` to recognize the originating IP to properly ban it. + +First, we have to add the following to the nginx configuration file located in `/mnt/user/appdata/letsencrypt/nginx/site-confs/default`. + +``` +proxy_set_header X-Real-IP $remote_addr; +proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; +``` + +This snippet should be added within your Home Assistant server config, so you have something like the following: + +``` +server { + ... + location / { + proxy_pass http://192.168.0.100:8123; + proxy_set_header Host $host; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } + + location /api/websocket { + proxy_pass http://192.168.0.100:8123/api/websocket; + proxy_set_header Host $host; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } + ... +} +``` + +Once that's added to the nginx configuration, we need to modify the Home Assistant `configuration.yaml` such that the `X-Forwarded-For` header can be parsed. This is done by adding the following to the `http` component: + +```yaml +http: + use_x_forwarded_for: True +``` + +At this point, once the Let's Encrypt and Home Assistant dockers are restarted, Home Assistant should be correctly logging the originating IP of any failed login attempt. Once that's done and verified, we can move onto the final step. + +#### Add the fail2ban sensor + +Now that we've correctly set everything up for Docker, we can add our sensors to `configuration.yaml` with the following: + +```yaml +sensor: + - platform: fail2ban + jails: + - hass-iptables + file_path: /fail2ban/fail2ban.log +``` + +Assuming you've followed all of the steps, you should have one fail2ban sensor, `sensor.fail2ban_hassiptables`, within your front-end. + +### {% linkable_title Other debug tips %} + +If, after following these steps, you're unable to get the fail2ban sensor working, here are some other steps you can take that may help: + +- Add `logencoding = utf-8` to the `[hass-iptables]` entry +- Ensure the `failregex` you added to `filter.d/hass.local` matches the output within `home-assistant.log` +- Try changing the datepattern in `filter.d/hass/local` by adding the following entry (change the datepattern to fit your needs). [source](https://github.com/fail2ban/fail2ban/issues/174) + ``` + [Init] + datepattern = ^%%Y-%%m-%%d %%H:%%M:%%S + ``` diff --git a/source/images/supported_brands/fail2ban.png b/source/images/supported_brands/fail2ban.png new file mode 100644 index 0000000000000000000000000000000000000000..e834a38bf869997a2dd1ba688fdd00b6ff66fb4e GIT binary patch literal 17857 zcmXtA19Tkk+l{S84K|IP#x@(=M2!DdaImxt9AG1?lccN|>;g1A1~lh`Tz?uE7!jDHsE~@=%2}qXmx@W}=jJ4r za=eTO5x50JZmw@f_#aWx#Zz5ytku?wkH#?d#YPuhXXlQ__0tnwPlmEeXnZLw@ES#^ zd$BD~O|CCP*U?hFrfC(tTTS3qSpkXPERQTT8+P%exRGzjJT0}wo zfW+{{2n!2~qNAp^fAQk?YH8U!*pE%mp6s4cf=NnLWH(2%X-YR>l<@TAA@CL;I6r@S z_vYs2hJ%KvZ)#N1Ru++!MQ&(l*aR!{O=Q<-gk1Fv^6}pdh7GZrWeo;@g$Ra>M?^%7 z{>Ew^W4x)D$9b}3jO%lhlK{N7md4QEHJyM#NI$Tr_o)q(8XV5dt!v-a3bnV+N(^|Y zCy!fGe*Ml22DNg7(SMO=OEvz5g@tyGj`96;UGT&s2vG?L6qNG>74%W(=YP#Fln$1aVJXzs5i`hFtgTI~ zzIoyBgHX8PU{C^fj8@*flf18?N0aII>r6(MYTa2@8?A4}^QO&w7yTMMrQ`EclvZsn zAd#K~A|lbZtPI=@4Rd%eo_6=go7O41bXt_8`eK-I5*+$qsP(-yM-Ukj9Hxk<4Ih&h zY4;PTl{UQF5^fKrH8rVC#Df!*M&y$jk`Kqz$b(S{>2>MV!JcUCKngLLnH`Jt55imW z-LKud-AoUt`!8L-aKr(V>;zTr9eVClLa@VwS#H8V{s>XaDvwlX7kKSsQBU&7kL2dA z!-^KNxm70|W>G48h|4L|w_$%tzqwQR~0R_?wo)d@GAs zC8_7D`|YO^{vSg^-jhI)Yiq347$7 zgMr8gmSDzjPuC99xneVnNYp&s`Ob^FN=Zo{jDpk71Wqvt@_gjLRk(wNxH(9-P1-1@ zvk+$~IxjIVSaNYOy}M4SO>QDK2quVv_Ju=})6)G!alX~S33;GEXlO{~urML#OG1@_ zLgC$wV5u+4_6Ym4V^n{b9n5nX5Q*PY>z&dn2L~Nb_zri`iipA;viR}gTG?^I-DtI} zg!%^EoY%Fv0QttM$+C8fFH7&{Uih}UuDmxnNkA)(JemA^j!rijI>i^f{|u`^Js%NA zSdw;v3g)FbE_LW9+7Iy4#jcMAtIMMpQ%<`5yJMvnF98|rSQ`R6--N18nu3IzvP9Z_ zT(b;fKa{OY;gH;q1FnaL--zIL*Q`&s{;pfY%fS-;Bp|kH*k0DT#X4j0@6HWuDyoZ0 z4IQDSX)cY{wr1Lqfri)q*t&}?w-Y?i<7dlzPw#dUT-8>%q9kqJQ$qd*M^h7QRw-Ki z**n}?T7Mf&^n!4Tsc`n*n5a`f_-+~jE=k&LR zntlg|f{{O08(!N|;W&UKzQVzy=UW)yFh!&Y(V3#LAsI1+YmAZMg?|ZmK|`WxZSGi? zm$u}Q9rt#bYpTnmmJshI!i-{wS6Cv#VTTJs`ePVxutWr6f6aW47u3`H=JPSCpW;2i z_0xI<>Z=}HnYw=q;$_q4huwlEqjM=qUB<-3zC($&tTM$2E03+LGE-5{Ux-1c68_ZHw%)f4kk}1UEmlo{~JY@HTaIZ$r~VUW5uF85-eGF!d2(vxWYXk&!k^LzkAKQ#R66;xiq%^f!@=c=}95 zpJkn^mB}|D$`4I|nPC>fBVx_R64FwHqG*MYEArRTXD?e=bey-o+_5{neZq)#94RT< z(Q8JdZ$nzBx?By#VMj6@^OcM@xHG4sQ?Yc-uaK?y_oG1e+i%Q;@?%SOG&wHlk1JT0 z2!hcLj?J;(kDG*GSzz>+)XQ z(;ZBBP-|J4(^yIWI`CD$9j+MW;ym)}W;~Q%os~<1U~o2JHdmmPz8nnWPlTUwa^-e^ zEQ%T8+Q%-i4J-`$t5xAOX83>dk~HKQmH0WvyeDD9eQjcSkF>l2jZp}72bkG2ih$IbF zpJO2YomKT8K5Y?;5@Y`gE=($YPe*E3zAK7gkPFh|`sd~z8*6cy&+fmC-+ROH+pVWt zGt%2JA_>-;+B2zCJi*j-dA+8$w zwu>9-q%Tl7rF>Zw>8S*`JfR8-MCKEt*X|k4@Q?~Oqf9-)f)5&G#XK4O)S=R}{f22Z zYM=0Jns1?XHvD+6uCkYXy217m)k*k2nq75zC%p^n2j)s>{9oP!)kc;H1oXICP8aS$ zs+vhRnn?aVUv;`ew);{!Z1oHoaX^Ne3p_67UD8`2vm*lG`n5%wF_WF7sG_bOttr?g zD$NH9a)$Ei&2>oSa6=LdJ&MJ0jS(jNjbIsKMD1H))h6qvHm#>(?CL?yyBlq(-1a0l z7j0iq1=e2U9X_5%xtPH(WHAC{)B<#iXMfGMTuHx2^MWsNe!Is-iA`F|TLui0&dxjuw zUHR%2yD^vL!P>zUaDns~SKW_%^tSI^)vv=h-;$P-^$-}kBAWM;ISQ)v)ce7{l1q=2|w=19Pe!-nVQ?~~J0 z)M~m@$iMdLY~oN)q2rz*f2;(QDY8Z7^n|`@EqC_bTRA(Mwe|+0M4?YPF=}~&!8RUH zDd7!Uor8n8IT5EAe%kdFfs3F1vfk| z`D{Aw)i%6et&#c+)|%~`b$*wJ;qa&hPL`<&IXa?li=j=gMZCV<4v&u-U#ztRPMg^=`NgW|F_`%vOI)cr8LjrJL{rY*GMq+B|zgp9<6H_F%kRuOrRl z6#+F+xcy)&997Mz_weaF=-;s?yi%8O+M9Jsdm> z!#1TSW>@XKw~TTgG>2w*yc`3#vJ=VSvGw!l12zis=c!uryNlZaE@On=r<>!!*mf9g z<<=iW`mJHg?EH?7OxbjHMQ!bLw8EJ;;m6eq?j+Q&6<`Wu| z4-Y$q25lSgu54f$`PJ6e>TDer*M{@^i{yIHk_j$>k)EhOGsgy9p+{w@`edBVWZ?3L zok5B1khXci1f%iZpW)BVvES^bvfwBx_-3$(&pVpNL82(6E=}jnLgv>hf$t4ddS+I1 z0JS!i#SF!Ap?v$eDBE;2>AQ-Wnv$+=CPY+op+>6{wQ`Z%ev!aCwa@dYeznIfe_EmN z?Wm`aFTEy&ZPz&bAmQZPtX$vjwGI@hp)4(rToVgN(TC$ps7f&Abt3UxWVRLcd3+|k zL|TQ#j^HtIfJ=+!`|~gUw<8R>EY`r#q6~=3cK;NXA~Vw)TOWUEdOz`RlBj431HDb_ zFrTko9b|Mo@)tqK_)GN`7|6)TPwyXOK1@GY@d_Fm62-r{2Ryi7HEw#GR#>ezA}{05 zFj0!{2YbKmW@UTM$|`7&0-SQ_YP%2IG**SIesl{C=6#*ANL1-P%I+b~2SajeWXmzX zJy^oSI=Ph~Iar*~C$aSf+cd)yh4kiTYu!~9+D%KaW$UDD`)QX4zDk@h@clvhGc64d zIz}&`e}g_?`CvSKxz(ArMuSewQIzD%FH6hk*UitYd^A=)pZEI>3si;d=Rb%Z6vs3) zThE8M{7zKC1olw$$(GEFR_bF?2%Ow+-X@Om1U#`$e?(EY&^%_~8ztf;BuBc;C0j6A zEO0YpVd$Ic9D$A$;Q>2s)SkzZ{50YWFBYIo(Dd10E3731|ox?GKN`( zI|U>R(hw}lk3^S;5=PEI6N}3$V;mTirX!<*db#l!g-?>-^>K>EWELpYScFD%B7@9u zK8Qc!JJQZUVPIeBJh~!USMcOAUAX%k9k%>YnJpvB=@Rvi>BSvpBuDxIa(2v;hm1@U z#)Q;-Gr|fUy>`6k;^c&e5U2!37GMC(W8F&Rp1(r=Xum_Nfz~LMWj;_*HSxo}Os&Ut zlc}OT<5fz!q_UD9J_WJ-5|J}ac}z;eKx+$aJs_q7A*vy>!M|SLwoxb_q8Fd2UJjh} zQS|BpwT58ojYPC@S~D?rtW^q|9#M(ej+68OADLFYHwZaZVAL1;ma?>Cu47hGcLRW4rGwwF+P4MJ+PhU=&+|aF>3!c=3?bTR$Ua@ z_Yqpp{<}|zrUj{%KErCSY$SG6&MYG}j|eaHaw|rJo8Ds4?$J?z@LY8b{SuF|v!J~~5?=-$Zs?^|ZhvGq=i6UtiH+fSAo+Sf2scf?}I`MzE# zKk!y~TL*bwD2^trtY}5hXM~t&@>s+#-ipfy(o`a7E0}J+|FlI3$~X%lTji&{n_ra!(W@ zVbU3fMKAWKB8^{q%w;}#DaW+Gm_BvBvba4dm?$xG8Mm}B+8b?F{R7Sz&xNnHjUP1P zOnQpvC3LWVX)GyIYd}t+#RX;>0N^yS^%xn_&x zCo{sQoyE?Ozag=|rlEk|cD_dN+$q2y;l!wGYHBWM+l5qa*?Hayx%%&`;PoPu7WW_s zs|0UpnY)XKVVP3hOH99pwYpwJ3@1 zTX<9y3W;uQFK{S#DTNjZNlCTNr)pVlJD~}mRi&jQAe6_9Vp^I%v-0Xt`T&*1*3!mh zw!(3DcLxiM(q*HSyEJgVhwTg;GKI5+c~ltU*Gcsoaz)dzP@d2QL7GWYQW~9A*EJnG zm}~w$EDXZ5jm@p54XGD0?ZAZ77%n^AI^W8 znXwr4!?D|LjK$0I5AP@IPXvC|3t2r^qc~X5-eoxZ;5#|R{oD?IY0n{~N?yK)S)Ne>@5k~uK|M@^AQ4~y^aUXsA5G<`sH$FH^`Sa$ z{(g*2P9BWFW#RrEvuZmDhZem#IbWO`5Ij#VCME_gt9v3SJ1e7bFpM5P;C7H|h9;c< zM4cxdeWB~Id92b<#5Wv8fP}|`oqf}T@M@&?5bB>tMF{E{D2-o`*y#cVN?GDmjP&Ol z^AM1;*I?EC4neA~zEDjQ(L%60_Cf)-CV=RR+dDiYh4332;B|Lrw9(m_JURJg(|-K} z0THp~qV+U|-5M`Y@;i(;fivdrVDzDD*DFD^zz1hvFzR6lXLA&vTC71KJmOcER~Pbb z=SF5PsHetUlKopisX^*nqK;sbjc2o5P*6|i?l=2Cg%<&TiPexAGgE7K+E%ofN` z*z)`g2K_r{5;bbDBoC(SQBu<4NOQzqv{>qUUdt=34#dQcT!kUDr>{v8%~~vR2;0wo zMa%9$w3zeT5^A1QZ@6UIX*sm;0gW0X=<)IKHJ{IS9lIWA>TZcnCEKod7rN0MV6e!& zPZ~!ZGlfwLMUp)g5KKD(%MYLBWhj54&I{pM&7=klMz9I)Q@XIQm#OU|yW(%@GDbY* zfhWy@9nitBoJ1&5{y&71(&rY;`Q%l74QJO((`MYq5nGXSum0(Y(rAY5GQOj&Co#FN z&TNzO42I60E6p#bc5mB}2`_2T{o~m5>RYNYPEF_$f=*#HgxKHTpIcbC07-pw#$5C9 z`SC3us`=YfYQj&~YYseoeAgS1R=yvS@Bm_5Vt2PeN2TE%9T^B(Py-+V9i^9+U|5VU zw6k^P(W-#%VN-O#$fKe{+-g{o0eMbWrVwRC;UjW%(%f6p967WQkzHHRC#IK$A3R&) zp}?YQ$(1=$zx46r_isK(Sd{)+I^g}_^DRWiMn-ZgDk77Tup6yce^^*hpDt98Vu#0` z-_~3j2ImO8P`$k!UM-ug(@dam!MsYn>Z=61)?yz^noeeogX@Bh^_~f6zGrJX);B3@ zsr?WV5~}h-A>izHK}tAS`r3X`xphSyNn|{dkJFQxshCp|0;A%Fzn-1Qm#6K@NjTAlf>bz;QcGLTnIAH5~kkD+lP&TD7wO8sNL2n@9*PVM0 z3v+XW>z#o$htcl<%#MtVa6Y!*QVE>1-VpkLyl*g`Zboe!(FPh}zBHnupY3zeQ&Da0 zgfm=d6FX#F;&4_6&;3FS5Z*gD+`V?I^+b%aAC4XA^cQlSS+*gu9?yAINn%w?J|IJ| zTiFUxS&A?(bfpJ71T#@Ga<;%|m!jq}w@KdH$J%mg0ciUyJT!EQQmw62ywmT>1z@M7I z9p|TeD-*BQH*@}i7h?-^-EFW(G-rYKtcY>64hM{hM zE6c(3&<)9TT3#2z|4g%(lhX3k4_Koa`4`C zX8%4msBDJtg9D1(>5yNF!?O4n-D5IP(8({P(cHqqAm`Hs=hu33Rw*JhiK&IO!W;{{Aj6pK?8&(j zWv-W_JXZ*D6BBZ?OlR!y!|`3(zAfIlh!dwc)Hjso?|qJiGO2$mPuonD=%iCuvbwij zb{}8iVf=G|ABB+3Wrv1?o#BmzrnjRY_6>em&UEWHWhx^6(Koe0j$zL^pi|Ubz517> zt*s-1tM_YKVNYWEieAro={VP#U81AX3h3D+M&bR5Uo&VVaAmc^G2bV5L9 zVQypdW0o~{nhKV{2~AzcUaZNs=GQz8Fs)@-(F{oKzFoPaV%}M8RU&QKo&91_wH=eP zp>JMydU{VO#63giM2Fmcz(;^ZQm?2kF*Wh!PK~WN{_Wpjn#p2^`T}Qfj3fbOcr;FBu zqY`|222>q-2%7SVVlLM7C#eMe&!?YPXPCX*XE29oqGdCWLkLYfoLT~Z2iJ-79T=Ik zh@YG%wfZz6DlS>_m!empRTC4T5D{589s~M9TW4ZP#c$d+-=lzvPERiEe%bLzMNfZl zQdU)1ULH|eO7owpvQVKNY>@_U(|hj1LLVA7NrtbW{DgfE7V`y+_g%2tv)sdF|6(H2%zI3xp}_e2b6yf0|Wylz1v5TMY|(&DmP;Ut-m zpS=XYV`$WwBI|oUlP8(jKd!q{%1oYCbxi~ldZ!fk967I&Tz$Wy zO-N3@Z0-7jPy+78H+;1Xl{?*h0QVC@Tx~5M4%}FrsxH?;mo+#~1?v(@y#$Rtvx^wn zJX56V!2O6{mD=>d!6Q;vjumKr^$|ME~ko-44Tp#ce>J;L*% zg>sEE#Pt62IxxnDEV;&6hqN6T7$bwf1DywnP=LVI{UFKSIo!FA&Xc zL2}F9CGTUsk4Ps+&XhY&>Yobr-!qfjn&rY1(Ooe?NsP?6Ra0duar_CBf$F@KJ4pp>C0l386cnQc%CmB9gj`To=u|I6N+N0Q{fd zw`d#R;@8sJ#(13x3Oa9cfl8Z;n-ry`r6;u@x0-j&&41+zH`td$(X_r6wsc4P&OAK} z*dlPwzEezBoLD+rdr8CiDWn!yt12iWYFqxz{SoPK1=~#+5EY~4XK=Xb7g6UThPO%r z<{vHa5;83C!9*I(k9RPpC@X&4{?xP?r2pB9&!RH~v>!voig`olCV?;Aevn+BZ?`SZ zUtWFxKMU~ja{B6IUnK`IbSKl<_xTpBw9T~hr7T; z9f7!Y9+X#ost5*?*!`@`l7fgluY%jfM!bfwdh+*IFofVdO0k7+D@C!jQj@c6X5n8? z{8?Rk7VpjQ)y&AgZP7)7qt>iuXHFefHfzI=H)s``rS73njQPEECzRC9suwYa4kyai z-&@^&NN2?Hn(FFp{Cq2^o-~+4%eJW(u7+=15O(I9W2Zs0 zvQ_XIv^`C0ZQE%(jdLXuMbXsc0_OHAEo@cOt+$#Q_VTi(8?PP+g+O<4niY7MawbR~ z9e3TVIJjRV+&#t0wtutr4!_;x zBA_Go{TQcL0_vNape*89$pN@3=xs^_^%`)ImDJS!rJ7|)dVBM?R$?H*z?UX)Bqk<$ zJ#7d7ULZR?BU^idME&_QEd#aZ@2@m;;mCb@swGWQ@4HyMx){laO+q>T)ctIq32d>r z?^wcCiAsgOq>BeXAE2*HdIAB9GDkrho-Oj1^%@KVf)4QV@ua5x) z_6n_mlz4eHwk+M5Q^_Hv@ddz)(Ui=J%GT)0(za;{ghs?>{QctO{n)n2^lPrTp5o9C z_S;rP(}t0V{P^0i1xZtS4d9mf-A<~LR?H%2!Uw9X)0`p2?2m4@9C~=y(N_BULAsw6 zrZ08=ZiA;wP+D-B2Z=)*Qc^*pMtnnHXa}cV=si5$zI8UpmyJ4UUUz@;68mX_6_c1K zZes%u90@foZC-hK!i-WwhMZaME^TLif`#<$3r&qi0%;VdpUEip)$yNa8G436&x6!b zX5MvAiIQ&n4R@aV+J2M$k;MNPQn^OWAKI$+ILoRIwfn04*qIrniPmgEb^F31)-aOt~W>>K#nXB=J9V#+s68r{v{-9w(NH!{l5A<7Bj$8amM z#IeJ>GUHJiCIg?F5CEThShiFYxqXC&-QWM}cs(FM3`~taMh}5PbJUQ*_<=Zb!mF!3 zS0>|^)V0?xpFFn>-lt>vdDbi$hxhw199k+O^w4UffiThQiFMb_@kyVLTisK)rv0+2 zPNV0W{eV70V6p>h6Ue^*3m}?MC~M@i!@u0k-tBusL(|Y%TdAzcQs6Q{s8tyKc4ni@ z_G0F7IeThD+i_JI5jDpM{upBI4w-4$S0%WDug1~vO>;X1Ls8vAgMuKaZ))1T_vlhL zpdw`HpB9%tIIT*)1?+0OJNU`#a720);!|B$6YpzX*Pg8&(FvaDB7M)uRbaShWPq}K zKHLjs(;HW_&w+Wp53J{_;ec$~usBE5yg%B;;AdrV++qre8EYDy-~PDaX<=yz=|+c( zbKQ+OH<#s-K7hP>kc;jHsoLX0QW|x~JlB|DZ){8k-2xo3aL$#Dt}0JUqwrb1$1RAO zJgtz)VkY&c+1J|_T86ru93gA}FSbDwWXZb!Sh`-Yy1HI|p>RJLY`7n0dV~M7k(7jQ ze=c;WbZs~ihr<#0<~~erwN&lbwBZqM$N7f0ZdLV#!)oAm3X*N(6g7%U3OgBuH4q(E6|exOA|d*l-XCwKvPkzQfFMB(98E)o?q-b zlB1Mr>-~|%hi6s=|H|t+Fbs@&oP2#143|gEdH%jod*U=u{{!9f#p%HN3fy(`H^;QO z6RsWQl=Z&7k8hspGj%U6N^lKbJYY~>kI+^vb!3kR2*>urv&kY7b1%zgPfFX{qqw^- ztEhAAJO<+kc}|kb!eG#&J-l-9ZAGrZf^-PXALsckWw}vHbJ7^U7gdC zq)(KPdi!|`)T`ZF-3bhNzCiEI-!z$B4knYEH^3lo#PWGFzWhgZE~#1fLzXa$qsp~= z$~lGei~AsfRar3*T3{dtp>Ti;%(7MxXChANr;#Gfd<_i<`C$y?0|6+Nr^5VOOclJd z!|UK!H#9m*K{+_u8)yj^nEQ5tk095XDu7xTj{oQN2e?k3IVgk!DqS(tZXHUs8wB+!mAr72LfAQ zZf8u~MojdbPe#8~3Kq$`|2b*9-Pavd!v*^X2ovj6`W?0U3;EwX4=~7)W7k4AN%reiVG3P5{$XX5<^FM8$1%Ijj0Hfa4d z7%cdLBgX%cAf(dr;hUe7^gt7d^*LPK)#;_%TWAp#9o=41y6r!Y6YBcUx5B$d4Cw=)DT<*T%)OY4N_@XbkG_`!BSW2E%dWOT(MdM>#!} z0&K7~8X*c)0fW0ehquI{zU6eNM2tv?vk9Uk6wuJ_f^5^~u&n(rLV5IFVfsa_qEH?=1{kGzjgKxCCuZoTmL^1%6 zJ$Ko?eFn6Qf)Z*$m&RoCx&Ga0DjEm7Ex%>22TjtXd13o&yLP>=X@zy0-u_fHBZjXJ zFj`s=n3$ME0ih;-h8m)Ieo$0#up^Yw{9&osK^DZU$Skqd%6R>?-NH&*d%Jrg;x`X* z_ixwHj|w_EV-cw=iSe$xk;k-yt&qb($TZ0{P9?c(;t>jIdm*HAIHMbC5y5>U^}k;$ za)-N~gljSy8ai%icR)c2zZl2Gz7hj@t29T4=KT>`_wDCH_&{MqEA09Lj^I=A@tlkv zJI+67G3lpyl@nx`Va&f&z*}0l^{S%!att;7r|KDHWxqo~7^bChn_Hj%1y~O;6c!fS zSZZBBZZ5BuHV+&WW(zio_;O9&7u`kWpiU3oi~dV=78yDV%9$PQB@&)P&}!#m4EVDQ zzZcmho#y2IqP{#3&rP1pst75BB@8IaI(cV6i!43o;;>OkhxB=?!TZ5s9z%mQG<>YX zpRF}roR+GmUgQPer4IzjRBu~oB_*g64_?M?w@S;3;euO^le_jJIW~we5jsc$nw6!N zPw(smexdB+162)(>z$oh$*}kuvVIBYDyc-7+4%OifP5(FyR+}stbCW@Xp$C5ERLUG zh(!P2&dyYgF+k>JIPXsgs=}@DmpA}2^ z2MYZ`LZA3;w3ub{Z4^&&W%*udx~=J!u4~D7z-3pLt7&1`+}s&&$mY2kDay_$BPPzu z>gyy2E|c&$*XObP^RHJIn~s-X2koymqEgR*6^05J1T74~r)GA7bl5r7Q={Im$Oa#8 zGza6_y+zsF78dYZkFeLTs-ni4acOBkgmd8d_1Tw~^}@pIt~}ONRIJQ~VuT{_IfBaR z@Vu{O>?aMZ6x-&>e&cv?O+m$4WU^-wWX#L&2qup=|wc$5#|5bLA(H*8*F;5If%FD zLJOY;y0Xfu;B$sL^w7iOj0vJV@#LwMR#c*r(qBNBCZxR`G%^x4Jn;~hd2Tq7Q2;nW z0CWEt7LIu3#=CcLQ2lG30uTSNc9I{G>wa!`cw&MAPnAbJNLcahg9xzYPK?yrLucGb zQKF!ze#TkEh8~GYRp*P%G1{-p&nijjc|V%~PQpJdb=`sGulf<}UYzYOr4C4K%i~*~ zSWWouZ`UEXENF*W(hU|j3oMgYdz&Bs)b)R>BJ&>EaeiY%GEPP?d4U9N{~XV;@J2vr z$HXe>oajSYjXs{G+;M2JHu#x$ibv@42K_BM{d)J2l7S)Ed`=iHGDiefQ6Wa!+8R<- zl?R923U0c1g`N(N?aTotHJ7VhQxo1rB^3)FiCs{_SBL_nV)0pIBH61*D%3OyiVCN~mjgzkNiF5JB;?m__S)g8n`*K=;0fq33rt0W@zA$SB`@xaOVUy5x=GH(}1BkXKtx9~4=V z5qW$J!2C+9%wY)ecA_4D$`jFWx_G-n8htf3E3d4rtqty#Z?U4BWb%EJz~GLO6MfA~ zTpV_M{QKVC&-ldsf|3&Cz8D-Bi4x+1&`m-L^iV~ejOfB+oFFpvP{Xvis3^ul3qu@= z@o{Sv^-ChWNRogk!<71_vh`x+o^46 zWc=Uuj4L77nvTMt7N1vqpXb|b%`WfXkXN`@oL6c-^D}o}Iq?*+i~s?{nw5Ql#pBL< z@9?XV{$}q&g)+F&%)~tBgqTQBi0;1}RBNE+;2=SFb#P?MyA5YriqMp|)p%`7*e91N+2!+(XyGk!k|d%fRN zBzbXXqaJz-0)B7u$J?j<9z10XhcgXVWMs(xs485WQQ!{w%8CjZdgKFd{&#x{5KV4q zRXJS&d7%t2wBY1Z1RXtjWZBrt-A<^p++QsCpZ72XN=Yu^br-YQWm%T8o6qF!>LIz# z&(B#||06xYN;*3IC-Y@3_X~s8>6Jey8XBIboihQAGD@|KJ?B&__j7LBZp+0JnCi=# zx_*^B80wvi=>y$<1=IxQ!)YR1`C*D;E^5`3@rJ_&HFT0>E5~aG`}@n}QE^Gw0z5AD zc2h#Hap~#fz+D1|9giFTw=Nk+n*e$($bF0niRXf|UAZW3-(fq{kzh258YQo##gU@a zq7=)ukN{H0~8SnKpu^P?BB{q|w?zm&wZAkmZ`&5(!U zY&|U9=r2Z3#NJDA5b{HC0pLl#ym;K)-r@>)^M3#S{ox5hHHI|6Uoj6xQAI@*2wMyc z3}9kmDQaj)7#b2oLqmtY1_lNKXtwLb9r`1$--yYm1}DfcUuI5v9)zu=mD!&xRzwlX zQ=*gzt)XO;1~c6E6Bvgzbm18pR)AaQcG1!T?<2bCTw7NMY}_ABrfkF}Wc~>UI1ENJ z`H~>dUU*Ev38<8&SG?`pY1uZ%tZ2aMXix?J#~M2@kRlRf@YBRF=R|AF9CMTr&dI5I z=YG+B_kIzG>dB2=J_cKF+E8DyUr|i8QjRjcYCD4cS}g^Kgt@Yk=S%zj{1tocT<3@letWc#`nVZv94D zrX&%nCaA3hzfN@$4e3N&XErt_a>c^k0BQL1?c#!cr1nh5 zSg8TP3y77TSfEUlk}x&8^h=4HnF={G%n}E>Z3#LfZ=fgrt>B z<$Gugz09h7mduW+6}NPS1GO;Y#@uT=<9ZpN4d1O&j24-fDMC5mRRegumZEl3=2 z%1EP!rctLE+j30<_fXXrMx}ow!-y;Mj;*ApiNH;ZIcjLIKPQ&6agR$CF&L#$Y-^l( zPJ^7Cov+#ZMZ5if(Yz+lgRD23CSzr?MT)v&t<<=Crc1bdy&t(=in-FB{Um)XqxuV` z*4En9d%i4!3KLJoL4T#VqAi% zO0@c-ep)%uagpM4(0a}uN-)#PemZP%9uLIFeU?Mv0fK3df!*Oc#-l-foRL~9#bR8F zVxn>lx+(cDjm_|b;<7Snq=m1oSBOpKP@H=~A|KB^O#21YbQujX86s#!?dtqqJK>b? z;v3-4uLIBRf<)a>1UwIE2S;Q*N-Ytbs#!W`#><5RM?eUsP$aD#zoCiFvO8urC<^@P zWuoe{rH5&E9@on$D^1b4zad_Zg=dUsz2!pSD@emm=Zy>4x2iv+^fMGqE+a(}w9t%6 z1voRDzdJeD#DU>9(zuspB%fm|dJ$p2D0{RPqxOOE$M~i!{`qyRtL(K(hD*?V2Ni;8 zl$mP!Zldp8c03j|LgQNvgm6+Y%Vtq);#P1T3MXrRzq-76`*m8Ft46pC^P71IPF6No~DEtHss_Y4d z`NbXjjS9>oCuW4$?gwQ`z)sI1mu~@6HVG4AEOuXz6RK5u()F-~p-C&U++s3m^J=5J zg&;fYrG)o+UXm__>oXWS>d}nWAmgSX7%>qrl_br4(>XnTM> z)R#ygabh8f%Y?gWs5r~&`673?`76rZ%c{YnoMBpu*NEx-1B-B{Qr@zIgsEGtkEhR4ST4sW+_ zpOrr7>FDzF^8)~s20A|(Kvd(;W+46B3NgfbUf+&&nJnud@mA%R@Oo6mJV7H+c1cqX4IsY{~Hm4^LZzS~wcMmLlU-Nr#487++=5T!R z?qRy0cQ7eH zHe271y~X#%bsf1u*_YMA+Pa{&HV%MzV9{u_!j(>< z%c)^{&({}^!ceb7G;4$uPlB{444|ekx9Oxj{sQ{KQV37{BUY{hu^I`{LJFj}?|9cF zL0wW+b=iPg_w!zjU5zc~+Ud%=KgpAUfK!Z5G+LX5P+l5Sf8 zQydteDgl>RQB_q8NI(Go1`wU^kl$@t7qdYCTAi)G5I2vb>fKB3Ls2L0}cceV?>R_U)_k6IA~uCeg4>i zL;8(8Ai1o#gJ|}>UWmD%|Bsna;d+#~`5y_#06S$I+Cr6PR&G}tDbX*vZFQtPMPw`Y zU)B1_uo)R4m?H95HKw|cLJXl~A_OBehzd6jVd0inQsns!B+lj(jxRBTfPzX3R0 z93g*&-ysUtF)5qfVJRAlWjxO70+a%SezcR3EQ_JDhy96%y{V_YiKqRkhr+I>@Qmgt z-wObn8C^XK(Kht!c)|U{Ap!(3{3z0wmgjifY%gTHo3f&6gM&d&Jx8#NtC{{jQ0p$V zAI|J-SphNp98AcwF`VpKjXcGX9wfOG*!THYb6mAv*f5TNh31y8ohDiu(@)GbNYWkB zptUrqg-Wtvdyo(|Jr2up3zy8gIs;T7EQL$s<_LLqzmdW ze5s<(cvdus_U&qe%}i4!+3(JB`GXB-l!L?E2cZ z?#3`)vQ1-0Nz$}l-$9DD(t)ARYk}TP`PI8OUw!nI5Hu*@N)vAC-B0XDaavfJ4YxCv z(m-B_e}9@)Z(F@NjuYb_G@0GuYjWDmU@(fDXGY@(N&4^M zOz$70j*3sZky1Zl#G}1~h|1_ZU323%JmewRWM8Q1-m{($C)U+IthgK*R@hc_W!%oe z%sN%M)kNBG`+Xj;m1?4JatMgai|_lug4gCpjV8m;Aml^wT|3QeKjfIUBuB$G+OO6I z+H_QQhghU1F@$;Q7Q3svs&Q-cFt7O_x+#hR&>kvwNR%{IY~ZTh2H)j6&OEo;I2|*a zZ`M6uAsk5dqgn6deZRWkg797@p^z@L;$VT#4S;6#@xwDg;Wr#@Bfcp)JeYxh zx7?{Eed5ld4!dROQfS(Rt-62>{rB14BgT+Mai%^~vyDQA;8~~*KRun6$`1H2xFHiI zt;g@2W<9T9lpWlmfo+POG%*Svdlq9ID)ZrT-Y=X*`}Wy^h2z+EP&A*pl%FxznEwj_ z1pfQI>}?n;?CUlT1gEBIJzSb9N_OjLP7Q(Ba{$-{;F?jBSbLOcdkibqyX>wILSq^D2N@iv^^B-?@=QjG>9~ZF@i?MojRRf2iZe& z_B?fhlpsE`r1{^`Slgmy7km|i)IzO(Qm8x2q-Q6Rn;)gw?{iod6C7^yDj_*rXu=U` zi4bl~)f}2bpxIg=p$%Nx_u-7~*%+}SMz|@wGruE2cj;sgQ59Z$IB0uAL)_y;eEq@9 zxv^uPKb)l(e6c4KXg9!kX%h3#>$FwJK69$(^coJAp^b_;xD3O*INB2NBIwizao=Ds z^9bJyrD929{uq&_Fh;~w)$mRY@4#KI&*<&RT5L+=Mv3^+t9wHqOn)!&PJ5zkFykpa z{<%|Ga^Z)Gzt4E`RN>FDybd7;Scd$u6kIBVI8gi_Wk{`J@lnhS`#(8vNut!g{MB;i?xDitUZ2(}FHA|~U;s{et2|4KIC7#^=y0KF=L$ul z<@{d*NFtgMklZWWPxfO6nsv9+aJ>?dX4Ar1A4T`1rr2e0B#`<>Idgy9iPYntJ<8$m z_Rgmz$|wrszvrD-YODk&2^0(A1sO)#8z!b3WUCceS!HZLJ+!%77;P! zn2V%ERQs5TB7($vP2aH^=RPfFG{kga<}B>l+{?MEbMLtq?)mp9aME&7(zwvM17#t* zNtxZ&9^3#b5j<|$&!WihXG+x#u8!ipQL48p`=-{eP%f95ygW($dVNE7b?Vx&jN`n> zoF(#zaM9?@|G3CBb1uW)(~j_i<;)piI4gVo6=2L(E%)Y=HU zDX2rQ1=97=QX|+Y%}g4{t@OKA)6<+t r?~Xm#v5c?pMIRH7Cc56J