Alpine Linux - User contributions [en]

Setting up Explicit Squid Proxy

2020-05-14T14:23:50Z

Ginjachris: /* Blocking domains */ - fixed domain ACL link

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will be used to sign it. This spoofed certificate is then presented to the client when they access a site via the proxy.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package or {{Pkg|libressl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates libressl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.
Whether you are using OpenSSL or LibreSSL, the command to use is still 'openssl'.

====== Generate a self-signed certificate ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.

====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump bump all
## Prior to squid 3.5 it was done like this:
#ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump bump all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dropbox.com/s/6a38vcmksoevfsa/porndomains.acl?dl=1 here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-08-15T08:04:05Z

Ginjachris: /* SSL interception or SSL bumping */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will be used to sign it. This spoofed certificate is then presented to the client when they access a site via the proxy.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package or {{Pkg|libressl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates libressl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.
Whether you are using OpenSSL or LibreSSL, the command to use is still 'openssl'.

====== Generate a self-signed certificate ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.

====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump bump all
## Prior to squid 3.5 it was done like this:
#ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump bump all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Darkhttpd

2017-03-29T11:33:56Z

Ginjachris: /* man darkhttpd */ updated

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.
For example, you might wish to serve files from {{Path|/var/files}} instead, so you can edit the {{Path|/etc/init.d/darkhttpd}} file with an editor of your choice (vi, nano, vim or whatever) and make it like so:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

= Use =

Filesharing is made easy; simply add your files under the server root, by default {{Path|/var/www/localhost/htdocs}}

== Test ==

Create a test page under the server root, by default {{Path|/var/www/localhost/htdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
darkhttpd/1.12, copyright (c) 2003-2016 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.
Pass 0 to let the system choose any free port for you.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--no-listing
Do not serve listing if directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--default-mimetype string (optional, default: application/octet-stream)
Files with unknown extensions are served as this mimetype.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--forward-all url (default: don't forward)
Web forward (301 redirect).
All requests are redirected to the corresponding url.

--no-server-id
Don't identify the server type in headers
or directory listings.

--ipv6
Listen on IPv6 address.
</pre>

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-03-29T11:23:13Z

Ginjachris: /* Disable SSL interception for certain sites */ amended for squid 3.5 "## e.g ssl_bump bump all"

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will sign it.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package or {{Pkg|libressl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates libressl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.
Whether you are using OpenSSL or LibreSSL, the command to use is still 'openssl'.

====== Generate a self-signed certificate ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.

====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump bump all
## Prior to squid 3.5 it was done like this:
#ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump bump all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-03-29T11:21:32Z

Ginjachris: /* Amend /etc/squid/squid.conf */ corrected for squid 3.5 "ssl_bump bump all"

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will sign it.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package or {{Pkg|libressl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates libressl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.
Whether you are using OpenSSL or LibreSSL, the command to use is still 'openssl'.

====== Generate a self-signed certificate ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.

====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump bump all
## Prior to squid 3.5 it was done like this:
#ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-03-29T10:14:18Z

Ginjachris: /* Generate a self-signed certificate with OpenSSL */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will sign it.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package or {{Pkg|libressl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates libressl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.
Whether you are using OpenSSL or LibreSSL, the command to use is still 'openssl'.

====== Generate a self-signed certificate ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.

====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-03-29T10:11:38Z

Ginjachris: libressl added

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will sign it.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package or {{Pkg|libressl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates libressl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.
Whether you are using OpenSSL or LibreSSL, the command to use is still 'openssl'.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Alpine Package Keeper

2017-03-28T10:54:36Z

Ginjachris: added "Add a local Package" section

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system.
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''
 
'''apk''' is the tool used to install, upgrade, or delete software on a running sytem. 
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the [http://git.alpinelinux.org/cgit/apk-tools.git apk tool] - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

= Overview =

The '''apk''' tool has the following applets:

{|
| [[#Add a Package|add]]
| Add new packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Info on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache Maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|}

= Packages and Repositories =

Software packages for Alpine Linux are digitally signed tar.gz archives containing programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs".

The packages are stored in one or more ''repositories''. A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named {{Path|APKINDEX.tar.gz}} to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in {{Path|/etc/apk/repositories}}, one repository per line. If you booted from a USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this:

{{Cat|/etc/apk/repositories|/media/sda1/apks/}}

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'' or ''ftp:'' protocols. The following is a valid repository file:

{{Cat|/etc/apk/repositories|
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main
https://dl-3.alpinelinux.org/alpine/v2.6/main
ftp://dl-3.alpinelinux.org/alpine/v2.6/main
}}

{{Note|Currently, there are no public https or ftp repositories. The protocols are available for local repositories.}}

== Repository pinning ==

You can specify additional "tagged" repositories in {{Path|/etc/apk/repositories}}:

{{Cat|/etc/apk/repositories|
http://nl.alpinelinux.org/alpine/v2.6/main
@edge http://nl.alpinelinux.org/alpine/edge/main
@testing http://nl.alpinelinux.org/alpine/edge/testing
}}

After which you can "pin" dependencies to these tags using:

{{cmd|apk add stableapp newapp@edge bleedingapp@testing}}

Apk will now by default only use the untagged repositories, but adding a tag to specific package:

1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository

2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)

= Update the Package list =

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/cache/apk/}}, {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}



{{Tip|If using remote repositories, it is a good idea to do an '''update''' just before doing an '''add''' or '''upgrade''' command. That way you know you are using the latest software available.}}

= Add a Package =

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{Cmd|apk add openssh
apk add openssh openntp vim}}

If you only have the main repository enabled in your configuration, apk will not include packages from the other repositories. To install a package from the edge/testing repository without changing your repository configuration file, use the command below. This will tell apk to use that particular repository.

{{cmd|apk add cherokee --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

{{Note|Be careful when using third-party or the testing repository. Your system can go down.}}

= Add a local Package =

To install a locally available apk package, for example if this device has no internet access but you can upload apk packages directly to it, use the '''--allow-untrusted''' flag:

{{cmd|apk add --allow-untrusted /path/to/file.apk}}

Note that multiple packages can be given. When installing a local package, all dependencies should also be specified. For example:

{{cmd|apk add --allow-untrusted /var/tig-2.2-r0.apk /var/git-2.11.1-20.apk}}

= Remove a Package =
Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

= Upgrade a Running System =

To upgrade ''all'' the packages of a running system, use '''upgrade''':

{{cmd|apk update
apk upgrade
}}

To upgrade ''only a few'' packages, use the '''add''' command with the ''-u'' or ''--upgrade'' option:

{{cmd|apk update
apk add --upgrade busybox
}}

{{Note|Remember that when you reboot your machine, the remote repository will not be available until after networking is started. This means packages newer than your local boot media will likely not be installed after a reboot. To make an "upgrade" persist over a reboot, use a [[#Local Cache|local cache]].}}

= Search for Packages =
The '''search''' command searches the repository Index files for installable packages.

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}

= Info on Packages =

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information), or all information displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>http://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}

== Listing installed packages ==

To list all installed packages, use:

<pre>apk info</pre>

To list all installed packages in alphabetical order, with a description of each, do:

<pre>apk -vv info|sort</pre>

= Additional apk Commands =
In progress...

= Local Cache =

{{:Local_APK_cache}}

= Advanced APK Usage =

== Holding a specific package back ==

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

[[Category:Package Manager]]

Setting up Explicit Squid Proxy

2017-02-22T22:42:11Z

Ginjachris: /* Behaviour with SSL interception */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Typically the server-side connection is established first, using the information available in the CONNECT request from the client (such as the destination server and port) which allows Squid to spoof a certificate. The Common Name (CN) will reflect the destination server and the Squid certificate will sign it.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-02-22T22:22:07Z

Ginjachris: /* explicit forward proxy */ minor changes

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. Explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client, typically by issuing a 407 HTTP response. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-02-22T22:19:40Z

Ginjachris: /* transparent forward proxy */ minor changes

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server can be involved in client authentication; this will usually involve redirecting the client to a virtual domain, typically with a 401 HTTP response.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-02-01T23:22:46Z

Ginjachris: /* Blocking domains */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [http://ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2017-02-01T23:19:45Z

Ginjachris: corrected link to porndomains.acl

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2016-09-14T10:19:12Z

Ginjachris: /* Squid crashes after configuring HTTPS interception */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"

In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2016-09-14T10:18:43Z

Ginjachris: Added "Squid crashes after configuring HTTPS interception"

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

===== Squid crashes after configuring HTTPS interception =====

Squid may crash after configuring SSL interception. The service may report as running, but reviewing listening ports no longer shows Squid listening.
A review of /var/log/messages may show an error "The ssl_crtd helpers are crashing too rapidly, need help!"
In this instance, perform the following:

<pre>
rc-service squid stop
rm -rf /var/lib/ssl_db
/usr/lib/squid3/ssl_crtd -c -s /var/lib/ssl_db
rc-service squid start
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2016-09-14T09:39:34Z

Ginjachris: spelling correction only

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation appears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

User:Ginjachris

2016-06-07T11:27:36Z

Ginjachris:

Hello, my name is Chris and I'm a security consultant from the UK.

Here's some crazy Drum 'n' Bass:

[https://www.youtube.com/watch?v=mRCyDw594eo 'Doorway' by Usual Suspects (Gridlock & Echo remix)]

[https://www.youtube.com/watch?v=IlXOcWYA_KY 'No test' by Distorted Minds]

[https://www.youtube.com/watch?v=r6QR8A9_iFU 'Chubrub' by Ed Rush & Optical]

[https://www.youtube.com/watch?v=5hVtvm44V94 'Science' by Ganja Kru]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server

* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

* knot: authoritative dns server setup

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

How to setup a Alpine Linux mirror

2016-06-07T11:15:18Z

Ginjachris: added darkhttpd configuration

This document describes how to set up an Alpine Linux mirror and make it available via http and rsync.

We will:
* create the dir where we have the mirror
* set up a cron job to sync with master mirror every hour
* set up lighttpd for http access
* set up rsync so other mirrors can rsync from you

Make sure that you have enough disk space; each v3.x branch has around 20 GiB.

== Setting up the cron job ==
Install rsync which will be used to sync from the master mirror.
{{Cmd|apk add rsync}}

Save the following file as ''/etc/periodic/hourly/alpine-mirror''
<pre>
#!/bin/sh

# make sure we never run 2 rsync at the same time
lockfile="/tmp/alpine-mirror.lock"
if [ -z "$flock" ] ; then
exec env flock=1 flock -n $lockfile "$0" "$@"
fi

src=rsync://rsync.alpinelinux.org/alpine/
dest=/var/www/localhost/htdocs/alpine/

# uncomment this to exclude old v2.x branches
#exclude="--exclude v2.*"

mkdir -p "$dest"
/usr/bin/rsync \
--archive \
--update \
--hard-links \
--delete \
--delete-after \
--delay-updates \
--timeout=600 \
$exclude \
"$src" "$dest"

</pre>

Make it executable:
{{Cmd|<nowiki>chmod +x /etc/periodic/hourly/alpine-mirror</nowiki>}}

Now it will sync every hour. (given cron runs)

== Setting up HTTP access via lighttpd ==

Install the lighttpd server
{{Cmd|apk add lighttpd}}

Enable dir listings by uncommenting the following line in ''/etc/lighttpd/lighttpd.conf'':
dir-listing.activate = "enable"

Also set cache-control to force cache revalidate every 30 mins. Uncomment mod_setenv in ''/etc/lighttpd/lighttpd.conf'':
"mod_setenv",

Add also the following lines to ''/etc/lighttpd/lighttpd.conf'':
setenv.add-response-header += (
"Cache-Control" => "must-revalidate"
)

Start lighttpd and make it start at boot:
{{Cmd|rc-service lighttpd start
rc-update add lighttpd}}

{{Note|You may wish to consider [[Darkhttpd]] as an alternative to [[Lighttpd]]

If so, simply install, start and auto-start the webserver:

{{Cmd|apk add darkhttpd && rc-service darkhttpd start && rc-update add darkhttpd}}

Darkhttpd will, by default, offer directory listings and serve data from /var/www/localhost/htdocs/

See the main article on [[Darkhttpd]] for more configuration options}}

== Setting up rsyncd ==
Add the following lines to ''/etc/rsyncd.conf'':
<pre>
[alpine]
path = /var/www/localhost/htdocs/alpine
comment = My Alpine Linux Mirror
</pre>

Optionally set a bandwidth limit in ''/etc/conf.d/rsyncd''. In this example we limit to 500Kbytes/s (approx 5Mbit/s)
<pre>
RSYNC_OPTS="--bwlimit=500"
</pre>

Reference:
[[File:sync.sh]]

[[Category:Server]]
[[Category:Package Manager]]

Setting up Explicit Squid Proxy

2016-03-23T08:39:52Z

Ginjachris: added note about CONNECT method

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client. Connections to HTTPS sites through an explicit proxy will use the CONNECT HTTP method.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation apears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Setting up Explicit Squid Proxy

2015-12-23T15:35:44Z

Ginjachris: "#dns_defnames on" not "#dns_defnames enabled"

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation apears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames on
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

User:Ginjachris

2015-11-15T17:22:15Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some crazy Drum 'n' Bass:

[https://www.youtube.com/watch?v=mRCyDw594eo 'Doorway' by Usual Suspects (Gridlock & Echo remix)]

[https://www.youtube.com/watch?v=IlXOcWYA_KY 'No test' by Distorted Minds]

[https://www.youtube.com/watch?v=r6QR8A9_iFU 'Chubrub' by Ed Rush & Optical]

[https://www.youtube.com/watch?v=5hVtvm44V94 'Science' by Ganja Kru]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server

* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

* knot: authoritative dns server setup

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

User:Ginjachris

2015-11-13T09:30:01Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some crazy Drum 'n' Bass:

[https://www.youtube.com/watch?v=mRCyDw594eo 'Doorway' by Usual Suspects (Gridlock & Echo remix)]

[https://www.youtube.com/watch?v=IlXOcWYA_KY 'No test' by Distorted Minds]

[https://www.youtube.com/watch?v=r6QR8A9_iFU 'Chubrub' by Ed Rush & Optical]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server

* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

* knot: authoritative dns server setup

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

User:Ginjachris

2015-11-09T11:57:20Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some crazy Drum 'n' Bass:

[https://www.youtube.com/watch?v=mRCyDw594eo 'Doorway' by Usual Suspects (Gridlock & Echo remix)]

[https://www.youtube.com/watch?v=IlXOcWYA_KY 'No test' by Distorted Minds]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server

* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

* knot: authoritative dns server setup

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

Darkhttpd

2015-05-06T17:45:04Z

Ginjachris: replaced yet more 'hdoc' with 'htdoc' :¬S

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.
For example, you might wish to serve files from {{Path|/var/files}} instead, so you can edit the {{Path|/etc/init.d/darkhttpd}} file with an editor of your choice (vi, nano, vim or whatever) and make it like so:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

= Use =

Filesharing is made easy; simply add your files under the server root, by default {{Path|/var/www/localhost/htdocs}}

== Test ==

Create a test page under the server root, by default {{Path|/var/www/localhost/htdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--no-server-id
Don't identify the server type in headers
or directory listings.
</pre>

[[Category:Server]]

Darkhttpd

2015-05-06T09:05:07Z

Ginjachris: /* Use */

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.
For example, you might wish to serve files from {{Path|/var/files}} instead, so you can edit the {{Path|/etc/init.d/darkhttpd}} file with an editor of your choice (vi, nano, vim or whatever) and make it like so:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

= Use =

Filesharing is made easy; simply add your files under the server root, by default {{Path|/var/www/localhost/hdocs}}

== Test ==

Create a test page under the server root, by default {{Path|/var/www/localhost/hdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--no-server-id
Don't identify the server type in headers
or directory listings.
</pre>

[[Category:Server]]

Darkhttpd

2015-05-06T09:03:19Z

Ginjachris: /* Use */

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.
For example, you might wish to serve files from {{Path|/var/files}} instead, so you can edit the {{Path|/etc/init.d/darkhttpd}} file with an editor of your choice (vi, nano, vim or whatever) and make it like so:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

= Use =

Filesharing is made easy; simply add your files under the server root, by default {{Path|/var/www/localhost/hdocs}}

== Test ==

Create a test page under the server root, by default {{Path|/var/www/localhost/hdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--no-server-id
Don't identify the server type in headers
or directory listings.
</pre>

[[Category:Server]]

Darkhttpd

2015-05-06T09:01:55Z

Ginjachris: extended darkhttpd configuration section

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.
For example, you might wish to serve files from {{Path|/var/files}} instead, so you can edit the {{Path|/etc/init.d/darkhttpd}} file with an editor of your choice (vi, nano, vim or whatever) and make it like so:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="/var/files --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

= Use =

Filesharing is made easy; simply add your files under {{Path|/var/www/localhost/hdocs}}

== Test ==

Create a test page under {{Path|/var/www/localhost/hdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--no-server-id
Don't identify the server type in headers
or directory listings.
</pre>

[[Category:Server]]

Darkhttpd

2015-05-06T08:37:50Z

Ginjachris: edited more paths to document root

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/htdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/htdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.

= Use =

Filesharing is made easy; simply add your files under {{Path|/var/www/localhost/hdocs}}

== Test ==

Create a test page under {{Path|/var/www/localhost/hdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--no-server-id
Don't identify the server type in headers
or directory listings.
</pre>

[[Category:Server]]

Darkhttpd

2015-05-06T08:35:50Z

Ginjachris: corrected path to document root (Thanks Bryan!)

Darkhttpd is a simple, fast HTTP 1.1 web server for static content. It does not support PHP or CGI etc but is designed to serve static content, which it does very well. Darkhttpd would be an excellent alternative to [[Lighttpd]] for [[How to setup a Alpine Linux mirror|running an Alpine mirror]]

For a full list of features see the [http://unix4lyfe.org/darkhttpd/ darkhttpd homepage]

= Install =

{{Cmd|apk add darkhttpd}}

= Configure =

Default location of files to serve: {{Path|/var/www/localhost/htdocs}}

Default log path: {{Path|/var/log/darkhttpd/access.log}}

There's no configuration file for {{Pkg|darkhttpd}}, everything is controlled from the command line or in our case the OpenRC init file, which is stored in {{Path|/etc/init.d/darkhttpd}} and by default looks like this:

<pre>
#! /sbin/runscript

description="darkhttpd web server"
command="/usr/bin/darkhttpd"
command_args="${document_root:-/var/www/localhost/htdocs} --chroot --daemon --uid darkhttpd --gid www-data --log /var/log/darkhttpd/access.log"
procname="darkhttpd"
pidfile=""
stopsig="SIGTERM"
</pre>

So by default we will serve pages from {{Path|/var/www/localhost/hdocs}} and darkhttpd will run as a background daemon, [https://en.wikipedia.org/wiki/Chroot chrooted] to {{Path|/var/www/localhost/hdocs}} with a user of <code>darkhttpd</code> and group of <code>www-data</code>.
Logs will go to {{Path|/var/log/darkhttpd/access.log}}.
The default values have been chosen to provide sane, secure settings.

Change any of these values as you see fit, but it's a good idea to backup the file before making changes.

For a full list of available options, run: {{Cmd|darkhttpd}}

and amend the <code>command_args</code> line as you see fit.

= Use =

Filesharing is made easy; simply add your files under {{Path|/var/www/localhost/hdocs}}

== Test ==

Create a test page under {{Path|/var/www/localhost/hdocs}}

{{Cmd|echo "this is a test page" > /var/www/localhost/htdocs/index.html}}

{{Note| You don't have to create a test page; in a working environment darkhttpd will generate a directory listing if no index page is found.}}

Start the daemon: {{Cmd|rc-service darkhttpd start}}

Output should be something like this:
<pre>
* Starting darkhttpd ...
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
listening on: http://0.0.0.0:80/
chrooted to `/var/www/localhost/htdocs'
set gid to 82
set uid to 100
</pre>
Now point a browser to your darkhttpd server and you should get the index page, or a directory listing if you didn't create an index page.

Check the logfile: {{Cmd|tail /var/log/darkhttpd/access.log}}

== Controlling darkhttpd status ==

Stop, start and restart the daemon in the usual fashion:
{{Cmd|rc-service darkhttpd start}}

{{Cmd|rc-service darkhttpd stop}}

{{Cmd|rc-service darkhttpd restart}}

== Auto-start darkhttpd at boot ==

To add the daemon to the default runlevel so it auto-starts at boot, do: {{Cmd|rc-update add darkhttpd}}

= Troubleshooting =

* When restarting the daemon you may see an error message:
<pre>
Stopping darkhttpd ...
/lib/rc/sh/runscript.sh: line 202: can't create /sys/fs/cgroup/openrc/darkhttpd/tasks: nonexistent directory
Starting darkhttpd ...
</pre>

This error message appears to be benign and of no consequence so can be ignored. I can only replicate this error on a VMWare vSphere client.

* If the daemon will not start, ensure you haven't made a syntax error in the init script.

* Ensure the daemon is running with {{Cmd|rc-status}}

* Make use of the logs to check it is receiving requests. To do this, run {{Cmd|tail -f /var/log/darkhttpd/access.log}} and then send requests to the web server. If darkhttpd is receiving the requests, lines will be logged. If you don't see these lines, perhaps a firewall rule is blocking access to the server or there is a routing issue somewhere?
Use 'Ctrl C' to exit back to the prompt when finished testing.

= man darkhttpd =
<pre>
v-alpine-server:~# darkhttpd
darkhttpd/1.9, copyright (c) 2003-2013 Emil Mikulic.
usage: darkhttpd /path/to/wwwroot [flags]

flags: --port number (default: 8080, or 80 if running as root)
Specifies which port to listen on for connections.

--addr ip (default: all)
If multiple interfaces are present, specifies
which one to bind the listening port to.

--maxconn number (default: system maximum)
Specifies how many concurrent connections to accept.

--log filename (default: stdout)
Specifies which file to append the request log to.

--chroot (default: don't chroot)
Locks server into wwwroot directory for added security.

--daemon (default: don't daemonize)
Detach from the controlling terminal and run in the background.

--index filename (default: index.html)
Default file to serve when a directory is requested.

--mimetypes filename (optional)
Parses specified file for extension-MIME associations.

--uid uid/uname, --gid gid/gname (default: don't privdrop)
Drops privileges to given uid:gid after initialization.

--pidfile filename (default: no pidfile)
Write PID to the specified file. Note that if you are
using --chroot, then the pidfile must be relative to,
and inside the wwwroot.

--no-keepalive
Disables HTTP Keep-Alive functionality.

--forward host url (default: don't forward)
Web forward (301 redirect).
Requests to the host are redirected to the corresponding url.
The option may be specified multiple times, in which case
the host is matched in order of appearance.

--no-server-id
Don't identify the server type in headers
or directory listings.
</pre>

[[Category:Server]]

User:Ginjachris

2015-03-25T22:05:41Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some crazy Drum 'n' Bass:

[http://grooveshark.com/s/Doorway+Gridlock+Echo+Remix/aGkez?src=5 'Doorway' by Usual Suspects (Gridlock & Echo remix)]

[http://grooveshark.com/s/No+Test/3GHSp1?src=5 'No test' by Distorted Minds]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server

* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

* knot: authoritative dns server setup

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

Lighttpd Advanced security

2015-03-10T11:22:51Z

Ginjachris: /* FREAK attack (CVE-2015-0204) - added link to https://freakattack.com/ */

For higher security [[Lighttpd]] can be configured to allow https access.

==Generate Certificate and Keys==
Either generate the public key and certificate and private key using {{Pkg|openssl}}, or by using the ones generated by installing [[Alpine_Configuration_Framework_Design| ACF]]. You don't need to do both, just do one or the other. The former method, with OpenSSL, is preferred since it gives greater control.

===Generate self-signed certificates with openssl ===
To generate certificates, openssl is needed.

{{Cmd|apk add openssl}}

Change to the lighttpd configuration directory

{{Cmd|cd /etc/lighttpd}}

With the command below the self-signed certificate and key pair are generated. A 2048 bit key is the minimum recommended at the time of writing, so we use '-newkey rsa:2048' in the command. Change to suit your needs. Answer all questions.

{{Cmd|openssl req -newkey rsa:2048 -x509 -keyout server.pem -out server.pem -days 365 -nodes}}

Adjust the permissions

{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

=== Generate self-signed certificates with acf ===

Install the [[Alpine_Configuration_Framework_Design| ACF]]

{{Cmd|setup-acf}}

Copy the generated certificate to the lighttpd configuration directory.

{{Cmd|mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server.pem}}

Adjust the permissions

{{Cmd|chown root:root /etc/lighttpd/server.pem}}
{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

mini_http is no longer needed.

{{Cmd|/etc/init.d/mini_httpd stop && rc-update del mini_httpd}}

Removing the mini_http package

{{Cmd|apk del mini_httpd}}

==Configure Lighttpd==
The configuration of lighttpd needs to be modified.

{{Cmd|nano /etc/lighttpd/lighttpd.conf}}

Uncomment this section and adjust the path so 'ssl.pemfile' points to where our cert/key pair is stored. Or copy the example below into your configuration file if you saved it to /etc/lighttpd/server.pem.
<pre>
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"
</pre>

You'll also want to set the server to listen on port 443. Replace this:
server.port = 80
with this:
server.port = 443

Restart lighttpd

{{Cmd|rc-service lighttpd restart}}

== Security ==

=== BEAST attack, CVE-2011-3389 ===
To help mitigate the BEAST attack add the following to your configuration:

#### Mitigate BEAST attack:

# A stricter base cipher suite. For details see:
# http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-3389
# or
# http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3389

ssl.cipher-list = "ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM"
#
# Make the server prefer the order of the server side cipher suite instead of the client suite.
# This is necessary to mitigate the BEAST attack (unless you disable all non RC4 algorithms).
# This option is enabled by default, but only used if ssl.cipher-list is set.
ssl.honor-cipher-order = "enable"

# Mitigate CVE-2009-3555 by disabling client triggered renegotiation
# This option is enabled by default.
#
ssl.disable-client-renegotiation = "enable"
#

=== Perfect Forward Secrecy (PFS) ===

[https://en.wikipedia.org/wiki/Perfect_forward_secrecy Perfect Forward Secrecy] isn't perfect, but what it does mean is that an adversary who gains the private key of a server does not have the ability to decrypt every encrypted SSL/TLS session. Without it, an adversary can simply obtain the private key of a server and decrypt and and all SSL/TLS sessions using that key. This is a major security and privacy concern and so using PFS is probably a good idea long term. It means that every session would have to be decrypted individually, regardless of the state (whether obtained by the adversary or otherwise).

Ultimately when choosing SSL/TLS ciphers it is the usual chose of security or usability? Increasing one usually decreases the other. Nonetheless, an example to prevent the BEAST attack and offer PFS is:

<pre>
ssl.cipher-list = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
</pre>

=== POODLE attack (CVE-2014-3566) ===

In light of the recent [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3566 POODLE] findings, it's advisable to wherever possible turn off support for SSLv3. This is quite simple, you can just append the following to your cipher list to explicitly disable SSLv3 support:

<pre>
:!SSLv3
</pre>

=== FREAK attack (CVE-2015-0204) ===

To prevent the so called [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-0204 FREAK] attack, keep your SSL library up to date, and do not offer support for export grade ciphers.

There's multiple ways to do this, like turning off export cipher support in the cipher list:

<pre>
:!EXPORT
</pre>

Although now might be a good time to review the cipher list in use, and use a stronger, explicit set like the one from the Perfect Forward Secrecy section, or another example:

<pre>
ssl.cipher-list = "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!3DES:!MD5:!PSK"
</pre>

Also see https://freakattack.com/

== Other configurations ==
The following are example configs, they will likely need to be modified to suite your particular setup. Nonetheless they should provide an indication of how to implement the relevant configuration options.

=== redirecting HTTP to HTTPS ===
Any requests to the server via HTTP (TCP port 80 by default) will be redirected to HTTPS (port 443):

<pre>
server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Ensure mod_redirect is enabled!
server.modules = (
"mod_redirect",
)

$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}

$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
## Make sure the line above points to your SSL cert/key pair!
}

</pre>

=== Serving both HTTP and HTTPS requests ===
Simple, just add in the SSL server port, enable the SSL engine and point to the relevant SSL cert/key pair:

<pre>

server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Below is HTTPS setup. Make sure to point at relevant cert/key pair for HTTPS to work!
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
}
</pre>

== More details ==
* [http://redmine.lighttpd.net/wiki/1/Docs:SSL Lighttpd documentation]

[[Category:Server]]
[[Category:Security]]

Lighttpd Advanced security

2015-03-10T11:18:58Z

Ginjachris: /*Added FREAK attack reference */

For higher security [[Lighttpd]] can be configured to allow https access.

==Generate Certificate and Keys==
Either generate the public key and certificate and private key using {{Pkg|openssl}}, or by using the ones generated by installing [[Alpine_Configuration_Framework_Design| ACF]]. You don't need to do both, just do one or the other. The former method, with OpenSSL, is preferred since it gives greater control.

===Generate self-signed certificates with openssl ===
To generate certificates, openssl is needed.

{{Cmd|apk add openssl}}

Change to the lighttpd configuration directory

{{Cmd|cd /etc/lighttpd}}

With the command below the self-signed certificate and key pair are generated. A 2048 bit key is the minimum recommended at the time of writing, so we use '-newkey rsa:2048' in the command. Change to suit your needs. Answer all questions.

{{Cmd|openssl req -newkey rsa:2048 -x509 -keyout server.pem -out server.pem -days 365 -nodes}}

Adjust the permissions

{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

=== Generate self-signed certificates with acf ===

Install the [[Alpine_Configuration_Framework_Design| ACF]]

{{Cmd|setup-acf}}

Copy the generated certificate to the lighttpd configuration directory.

{{Cmd|mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server.pem}}

Adjust the permissions

{{Cmd|chown root:root /etc/lighttpd/server.pem}}
{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

mini_http is no longer needed.

{{Cmd|/etc/init.d/mini_httpd stop && rc-update del mini_httpd}}

Removing the mini_http package

{{Cmd|apk del mini_httpd}}

==Configure Lighttpd==
The configuration of lighttpd needs to be modified.

{{Cmd|nano /etc/lighttpd/lighttpd.conf}}

Uncomment this section and adjust the path so 'ssl.pemfile' points to where our cert/key pair is stored. Or copy the example below into your configuration file if you saved it to /etc/lighttpd/server.pem.
<pre>
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"
</pre>

You'll also want to set the server to listen on port 443. Replace this:
server.port = 80
with this:
server.port = 443

Restart lighttpd

{{Cmd|rc-service lighttpd restart}}

== Security ==

=== BEAST attack, CVE-2011-3389 ===
To help mitigate the BEAST attack add the following to your configuration:

#### Mitigate BEAST attack:

# A stricter base cipher suite. For details see:
# http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-3389
# or
# http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3389

ssl.cipher-list = "ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM"
#
# Make the server prefer the order of the server side cipher suite instead of the client suite.
# This is necessary to mitigate the BEAST attack (unless you disable all non RC4 algorithms).
# This option is enabled by default, but only used if ssl.cipher-list is set.
ssl.honor-cipher-order = "enable"

# Mitigate CVE-2009-3555 by disabling client triggered renegotiation
# This option is enabled by default.
#
ssl.disable-client-renegotiation = "enable"
#

=== Perfect Forward Secrecy (PFS) ===

[https://en.wikipedia.org/wiki/Perfect_forward_secrecy Perfect Forward Secrecy] isn't perfect, but what it does mean is that an adversary who gains the private key of a server does not have the ability to decrypt every encrypted SSL/TLS session. Without it, an adversary can simply obtain the private key of a server and decrypt and and all SSL/TLS sessions using that key. This is a major security and privacy concern and so using PFS is probably a good idea long term. It means that every session would have to be decrypted individually, regardless of the state (whether obtained by the adversary or otherwise).

Ultimately when choosing SSL/TLS ciphers it is the usual chose of security or usability? Increasing one usually decreases the other. Nonetheless, an example to prevent the BEAST attack and offer PFS is:

<pre>
ssl.cipher-list = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
</pre>

=== POODLE attack (CVE-2014-3566) ===

In light of the recent [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3566 POODLE] findings, it's advisable to wherever possible turn off support for SSLv3. This is quite simple, you can just append the following to your cipher list to explicitly disable SSLv3 support:

<pre>
:!SSLv3
</pre>

=== FREAK attack (CVE-2015-0204) ===

To prevent the so called [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2015-0204 FREAK] attack, keep your SSL library up to date, and do not offer support for export grade ciphers.

There's multiple ways to do this, like turning off export cipher support in the cipher list:

<pre>
:!EXPORT
</pre>

Although now might be a good time to review the cipher list in use, and use a stronger, explicit set like the one from the Perfect Forward Secrecy section, or another example:

<pre>
ssl.cipher-list = "ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!3DES:!MD5:!PSK"
</pre>

== Other configurations ==
The following are example configs, they will likely need to be modified to suite your particular setup. Nonetheless they should provide an indication of how to implement the relevant configuration options.

=== redirecting HTTP to HTTPS ===
Any requests to the server via HTTP (TCP port 80 by default) will be redirected to HTTPS (port 443):

<pre>
server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Ensure mod_redirect is enabled!
server.modules = (
"mod_redirect",
)

$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}

$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
## Make sure the line above points to your SSL cert/key pair!
}

</pre>

=== Serving both HTTP and HTTPS requests ===
Simple, just add in the SSL server port, enable the SSL engine and point to the relevant SSL cert/key pair:

<pre>

server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Below is HTTPS setup. Make sure to point at relevant cert/key pair for HTTPS to work!
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
}
</pre>

== More details ==
* [http://redmine.lighttpd.net/wiki/1/Docs:SSL Lighttpd documentation]

[[Category:Server]]
[[Category:Security]]

Lighttpd Advanced security

2015-02-23T12:13:04Z

Ginjachris: removed RC4 from PFS section (rc4 not recommended) and removed source link (unnecessary)

For higher security [[Lighttpd]] can be configured to allow https access.

==Generate Certificate and Keys==
Either generate the public key and certificate and private key using {{Pkg|openssl}}, or by using the ones generated by installing [[Alpine_Configuration_Framework_Design| ACF]]. You don't need to do both, just do one or the other. The former method, with OpenSSL, is preferred since it gives greater control.

===Generate self-signed certificates with openssl ===
To generate certificates, openssl is needed.

{{Cmd|apk add openssl}}

Change to the lighttpd configuration directory

{{Cmd|cd /etc/lighttpd}}

With the command below the self-signed certificate and key pair are generated. A 2048 bit key is the minimum recommended at the time of writing, so we use '-newkey rsa:2048' in the command. Change to suit your needs. Answer all questions.

{{Cmd|openssl req -newkey rsa:2048 -x509 -keyout server.pem -out server.pem -days 365 -nodes}}

Adjust the permissions

{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

=== Generate self-signed certificates with acf ===

Install the [[Alpine_Configuration_Framework_Design| ACF]]

{{Cmd|setup-acf}}

Copy the generated certificate to the lighttpd configuration directory.

{{Cmd|mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server.pem}}

Adjust the permissions

{{Cmd|chown root:root /etc/lighttpd/server.pem}}
{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

mini_http is no longer needed.

{{Cmd|/etc/init.d/mini_httpd stop && rc-update del mini_httpd}}

Removing the mini_http package

{{Cmd|apk del mini_httpd}}

==Configure Lighttpd==
The configuration of lighttpd needs to be modified.

{{Cmd|nano /etc/lighttpd/lighttpd.conf}}

Uncomment this section and adjust the path so 'ssl.pemfile' points to where our cert/key pair is stored. Or copy the example below into your configuration file if you saved it to /etc/lighttpd/server.pem.
<pre>
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"
</pre>

You'll also want to set the server to listen on port 443. Replace this:
server.port = 80
with this:
server.port = 443

Restart lighttpd

{{Cmd|rc-service lighttpd restart}}

== Security ==

=== BEAST attack, CVE-2011-3389 ===
To help mitigate the BEAST attack add the following to your configuration:

#### Mitigate BEAST attack:

# A stricter base cipher suite. For details see:
# http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-3389
# or
# http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3389

ssl.cipher-list = "ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM"
#
# Make the server prefer the order of the server side cipher suite instead of the client suite.
# This is necessary to mitigate the BEAST attack (unless you disable all non RC4 algorithms).
# This option is enabled by default, but only used if ssl.cipher-list is set.
ssl.honor-cipher-order = "enable"

# Mitigate CVE-2009-3555 by disabling client triggered renegotiation
# This option is enabled by default.
#
ssl.disable-client-renegotiation = "enable"
#

=== Perfect Forward Secrecy (PFS) ===

[https://en.wikipedia.org/wiki/Perfect_forward_secrecy Perfect Forward Secrecy] isn't perfect, but what it does mean is that an adversary who gains the private key of a server does not have the ability to decrypt every encrypted SSL/TLS session. Without it, an adversary can simply obtain the private key of a server and decrypt and and all SSL/TLS sessions using that key. This is a major security and privacy concern and so using PFS is probably a good idea long term. It means that every session would have to be decrypted individually, regardless of the state (whether obtained by the adversary or otherwise).

Ultimately when choosing SSL/TLS ciphers it is the usual chose of security or usability? Increasing one usually decreases the other. Nonetheless, an example to prevent the BEAST attack and offer PFS is:

<pre>
ssl.cipher-list = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256"
</pre>

=== POODLE attack (CVE-2014-3566) ===

In light of the recent [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3566 POODLE] findings, it's advisable to wherever possible turn off support for SSLv3. This is quite simple, you can just append the following to your cipher list to explicitly disable SSLv3 support:

<pre>
:!SSLv3
</pre>

== Other configurations ==
The following are example configs, they will likely need to be modified to suite your particular setup. Nonetheless they should provide an indication of how to implement the relevant configuration options.

=== redirecting HTTP to HTTPS ===
Any requests to the server via HTTP (TCP port 80 by default) will be redirected to HTTPS (port 443):

<pre>
server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Ensure mod_redirect is enabled!
server.modules = (
"mod_redirect",
)

$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}

$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
## Make sure the line above points to your SSL cert/key pair!
}

</pre>

=== Serving both HTTP and HTTPS requests ===
Simple, just add in the SSL server port, enable the SSL engine and point to the relevant SSL cert/key pair:

<pre>

server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Below is HTTPS setup. Make sure to point at relevant cert/key pair for HTTPS to work!
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
}
</pre>

== More details ==
* [http://redmine.lighttpd.net/wiki/1/Docs:SSL Lighttpd documentation]

[[Category:Server]]
[[Category:Security]]

Alpine Linux:FAQ

2015-01-02T11:30:34Z

Ginjachris: /* My cron jobs don't run? */ amended "-t" to "--test"

[[Image:filetypes.svg|64px|left|link=]]
This is a list of '''frequently asked questions''' about Alpine Linux. 
If your question is not answered on this page, use the search box above to find work in progress pages not linked here, or in case of no answer, edit this page and write down your question.
{{Tip| Prepare your question. Think it through. Make it simple and understandable.}}

=General=

To get oriented and learn what makes our distribution distinctive, see the [http://alpinelinux.org/about About page] or [[Alpine Linux:Overview|our more detailed overview]].

== I have found a bug, where can I report it? ==
You can report it on the [http://bugs.alpinelinux.org/ bugtracker].

== Are there any details about the releases available? ==
Yes, please check the [[Alpine Linux:Releases|Releases]] page.

== Alpine freezes during boot from Compact Flash, how can I fix? ==
Most Compact Flash card readers do not support proper DMA. 
You should append '''nodma''' to the ''append'' line in {{path|syslinux.cfg}}.

== How can I contribute? ==
You can contribute by:
* using the software and giving feedback
* by documenting your [http://www.alpinelinux.org Alpine Linux] experiences on this [[Main_Page|wiki]]
* in many other ways
Please visit [[Contribute|Contribute page]] to read more about this topic.

Your contributions are highly appreciated.

== How do I remove the CDROM? ==
Since the modloop loopback device is on CDROM you cannot just run ''eject''. You need to unmount the modloop first. 
Unmounting both the modloop and the cdrom in one step can be done by executing:
{{cmd|/etc/init.d/modloop stop}}

Then it's possible to eject the cdrom:
{{cmd|eject}}

== Why don't I have man pages or where is the 'man' command? ==
The {{pkg|man}} command and man pages are not installed by default.

* First, install the {{pkg|man}} package:
: {{Cmd|apk add man}}
* Once that's done, install the documentation for the packages that you require man pages for: (Keep in mind, however, it's possible that not all packages will have a corresponding documentation package.)
: {{Cmd|apk add <pkg>-doc}}
: For example, say you installed {{pkg|iptables}} and you now require its {{pkg|man}} pages:
: {{Cmd|apk add iptables-doc}}
 
In our example above, we installed the man pages (and other documentation) for iptables. We can now read it:
{{Cmd|man iptables}}

==Booting Alpine on an HP ML350 G6==
{{Note|This 'Booting Alpine on an HP ML350 G6' section, only applies to [http://www.alpinelinux.org/ Alpine Linux] 1.9.3 and earlier.}}
[http://bugs.alpinelinux.org/issues/228 Ticket 228] on [http://bugs.alpinelinux.org/ bugs.alpinelinux.org] includes a patch that disables the kernel module hpwdt by default.

Details: Kernel module for HP Watchdog Timer causes issues during boot. Solution is to create an overlay (ie {{path|hpwdt.apkovl.tar.gz}}) containing {{path|/etc/modprobe.d/hpwdt}} (which contains "blacklist hpwdt"), place that on some removable media (ie USB key) and insert that during boot process. This will insure that the offending module doesn't load and that the server will boot properly.

==My cron jobs don't run?==
The cron daemon is started automatically on system boot and executes the scripts placed in the folders under {{path|/etc/periodic}} - there's a {{path|15min}} folder, plus ones for {{path|hourly}}, {{path|daily}}, {{path|weekly}} and {{path|monthly}} scripts.

You can check whether your scripts are likely to run using the command:

: {{cmd|run-parts --test /etc/periodic/[foldername]}} - for example: ''run-parts -t /etc/periodic/15min''

This command will tell you what should run but will not actually execute the scripts.

If the results of the test are not as expected, check the following:

* Make sure the script is executable - if unsure, issue the command : {{cmd|chmod a+x [scriptname]}}
* Make sure the first line of your script is :<pre>#!/bin/sh</pre>
* Do not put file extensions on your script names - this stops them from working; for example: {{path|myscript}} will run, but {{path|myscript.sh}} won't

== What is the difference between edge and stable releases? ==
Stable releases are just what they sound like: initially a point-in-time snapshot of the package archives, but then maintained with bugfixes only in order to keep a stable environment.

[[Edge]] is more of a rolling-release, with the latest and greatest packages available in the online repositories. 
Occasionally, snapshot ISO images of the then-current state of [[edge]] are made and are available for download. 
Typically these are made when there are major kernel upgrades or package upgrades that require initramfs rebuilds.

== What kind of release of Alpine Linux are available? ==
Please check the [[Alpine_Linux:Releases|Releases]] page for more information.

=Setup=

== What is the difference between 'sys', 'data', and 'diskless' installs when running setup-alpine (or setup-disk)? ==
'''sys:''' This mode is a traditional disk install. The following partitions will be created on the disk: /boot, / (filesystem root) and swap. 
This mode may be used for development boxes, desktops, virtual servers, etc.

'''data:''' This mode uses your disk(s) for data storage, not for the operating system. Only /var is created on disk. The system itself will run from tmpfs (RAM).

Use this mode if you only want to use the disk(s) for a mailspool, databases, logs, etc.

'''diskless:''' No disks are to be used. [[Alpine local backup]] may still be used in this mode.

== How can I install a custom firmware in a diskless system? ==

The modules and firmware are both special images which are mounted as read-only. 
To fix this issue you can copy the firmware directory to your writeable media (cf/usb) and copy your custom firmware to it. 
After reboot Alpine should automatically use the directory on your local storage instead of the loopback device.

=Audio=

== How do I play my .ogg/.mp3 files? ==
First, the sound card should be recognized (you must have {{path|/dev/snd/*****}} files)

{{pkg|sox}}, {{pkg|mpg123}}, etc all use the oss sound driver, while Alpine uses ALSA drivers. 
So you need to load the snd-pcm-oss compatibility module. 
While you're at it, you might need {{pkg|aumix}} to turn up the sound volume
{{cmd|echo snd-pcm-oss >> /etc/modules
modprobe snd-pcm-oss
apk_add aumix sox
aumix (set volume settings)
play really_cool_song.mp3}}

= Time and timezones =

== How do I set the local timezone? ==

Starting in Alpine 2.2, setting the timezone can be done through the [[Setup-alpine|setup-alpine]] script, and no manual settings should be necessary. 
If you wish to edit the timezone after installation, run the [[Alpine_setup_scripts|setup-timezone]] script.

However, if you are using a previous version, please use the following steps:

/etc/timezone and the whole zoneinfo directory tree are not supported.
To set the timezone, set the TZ environment variable as specified in
http://www.opengroup.org/onlinepubs/007904975/basedefs/xbd_chap08.html
or you may also create an /etc/TZ file of a single line, ending with a
newline, containing the TZ setting. For example
echo CST6CDT > /etc/TZ
''Source: http://www.uclibc.org/downloads/Glibc_vs_uClibc_Differences.txt''

For more information, see how other uClibc-based distributions do this:
* http://leaf.sourceforge.net/doc/buci-tz3.html
* http://www.sonoracomm.com/index.php?option=com_content&task=view&id=107&Itemid=32

For a more complete list of timezones, please see: http://en.wikipedia.org/wiki/List_of_tz_database_time_zones

== OpenNTPD reports an error with "adjtime" ==
Your log contains something like:
reply from 85.214.86.126: offset 865033148.784255 delay 0.055466, next query 32s
reply from 202.150.212.24: offset 865033148.779314 delay 0.400771, next query 3s
adjusting local clock by 865033148.779835s
adjtime failed: Invalid argument

{{pkg|openntpd}} is supposed to make small adjustments in the time without causing time jumps. 
If the adjustment is too big then something is clearly wrong and ntpd gives up. (its actually adjtime(3) that has a limit on how big adjustments are allowed)

You can make ntpd set the time at startup by adding ''-s'' option to ntpd. This is done by setting '''NTPD_OPTS="-s"''' in {{path|/etc/conf.d/ntpd}}.

== Using a cron job to keep the time in sync ==
Add the following to {{path|/etc/periodic/daily}} (or use another folder under the {{path|/etc/periodic}} heirarchy if you want to run the script more/less frequently)

Example: file called {{path|do-ntp}}
<pre>
#!/bin/sh
ntpd -d -q -n -p uk.pool.ntp.org</pre>

This queries the uk time server pool - you can modify this to suit your localisation, or just use ''pool.ntp.org''. More info here: [http://www.pool.ntp.org/zone/@ http://www.pool.ntp.org/zone/@]

== Windows clients reports an error when trying to sync ==
{{pkg|openntpd}} needs to run for a while before it is satisfied it is in sync.
Until then it will set a flag "clock not synchronized" and Windows will report an error while trying to sync with your {{pkg|openntpd}} server.

Only thing to do is wait, do something else for 15-20mins and then check.

= Packages =
== Can you build an apk package for ...? ==
Yes, we probably can. 
Please create an [http://redmine.alpinelinux.org/projects/alpine/issues/new issue] in the [http://bugs.alpinelinux.org bugtracker]. Mark it as "feature" and include a short description (one-line), an url for the home page, and an url for the source package.

== How can I build my own package? ==
Please see the [[Creating an Alpine package]] page.

== WARNING: Ignoring APKINDEX.xxxx.tar.gz ==
If you get <code>WARNING: Ignoring APKINDEX.xxxx.tar.gz: No such file or directory</code> while running package related tools, check your {{path|/etc/apk/repositories}} file if an entry points to {{path|.../v2.4/testing/}}. This directory is gone.

To check the content of the repositories file
{{Cmd|cat /etc/apk/repositories}}

or
{{Cmd|setup-apkrepos}}

= Dynamic DNS =
== How do I schedule a regular dynamic DNS update? ==
You'll want to install the {{pkg|ez-ipupdate}} package:
{{cmd|apk add ez-ipupdate}}

After that, create a new file at {{path|/etc/ezipupdate.conf}} with the contents similar to:
service-type=dyndns
user=myusername:mypassword
interface=eth1
host=myhostname.dyndns.org

Make the new ip cache directory:
{{cmd|mkdir /var/cache/ez-ipupdate
lbu add /var/cache/ez-ipupdate}}

Then schedule a new cron job with this command:
{{cmd|echo >> /var/log/ez-ipupdate && /bin/date >> /var/log/ez-ipupdate && ez-ipupdate --config /etc/ez-ipupdate.conf -f -F /var/run/ez-ipupdate.pid --cache-file /var/cache/ez-ipupdate/ipcache --quiet >> /var/log/ez-ipupdate 2>&1}}

Don't forget to backup your settings!
{{cmd|lbu ci}}

Entropy and randomness

2014-12-10T13:52:24Z

Ginjachris: /* Introduction */

== Introduction ==

[https://en.wikipedia.org/wiki/Entropy_%28computing%29 Entropy] is described as 'a numerical measure of the uncertainty of an outcome' and is often associated with chaos or disorder however is often more simply called [https://en.wikipedia.org/wiki/Randomness randomness].

It is important for a secure operating system to have sufficient quantities of entropy available for various crypotographic and non-cryptographic purposes, such as:

* Generation of cryptographic keys

* Address Space Layout Randomisation ([http://en.wikipedia.org/wiki/PaX#Address_space_layout_randomization ASLR]) - used by default in Alpine of course ;)

* TCP port randomisation ([https://en.wikipedia.org/wiki/Network_address_translation NAT], outbound connection)

* [https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Reliable_transmission TCP sequence number] selection (see [https://en.wikipedia.org/wiki/TCP_sequence_prediction_attack this too)]

* Writing random files for testing network functionality and throughput

* Overwriting hard disks prior to reuse or resale or encryption

Entropy is contained within a '''pool''', which draws its entropy from various '''sources'''. To view the current amount of entropy in the pool:

{{Cmd|more /proc/sys/kernel/random/entropy_avail}}

To view the maximum limit of entropy that the pool can hold:

{{Cmd|more /proc/sys/kernel/random/poolsize}}

On a standard system the limit is 4096 bits (512 bytes). The [https://grsecurity.net/ gr-sec] patch used on Alpine increases this limit to 16384 bits (2048 bytes).
Entropy is added to the pool in bits from various sources, "the relative number of unknown bits per event is roughly 8/keyboard, 12/mouse, 3/disk, 4/interrupt" [http://www.issihosts.com/haveged/history.html#intro source] meaning that on a headless server (without mouse and keyboard attached), which ironically is often a system requiring the most entropy, entropy generation is somewhat limited.

The entropy from the pool can be accessed in two ways by default:

'''/dev/random''' - This is a [https://en.wikipedia.org/wiki/Blocking_%28computing%29 blocking] resource, so it will use available entropy from the pool. If more entropy is required than is available, the process will wait until more entropy is available in the pool. Due to this behaviour, /dev/random is best used where small amounts of high quality randomness are required, such as for cryptographic keys.

'''/dev/urandom''' - Is a non-blocking resource. It uses a seed value from the same entropy pool as /dev/random and therefore, if little entropy is available in the pool, it is recommended not to use /dev/urandom until more entropy is made available in the pool. It runs the seed value through an algorithm and so is a [http://en.wikipedia.org/wiki/Pseudo-random_number_generator pseudo-random number generator], operating much faster than /dev/random. /dev/urandom is best used for non-cryptographic purposes such as overwriting disks.

Writing to /dev/random or /dev/urandom will update the entropy pool with the data written, but this will not result in a higher entropy count. This means that it will impact the contents read from both files, but it will not make reads from /dev/random faster.
For more information see the [http://linux.die.net/man/4/random random manpage]

It is generally recommended wherever entropy is used heavily to supply additional entropy sources; some possibilities are below. Adding more sources of entropy to feed into the pool is a good idea. It makes an attackers job more difficult, because there will be more sources they have to gain control over (or at the very least observe at source), and adding more sources of entropy, even weak ones, can only result in higher entropy.

If you are desperate for more entropy and are working on a headless server with no internet connection, you could try generating some via disk activity. Just don't expect any miracles! Here's an example:

<pre>dd if=/dev/zero of=/var/tmp/tempfile bs=1M count=200 && find / -size +1k && ls -R / && rm /var/tmp/tempfile && sync</pre>

If your server is a 'run-from-ram' setup and so you have no disks to create churn but require more entropy, it is strongly recommended to add alternative entropy sources as discussed below.

== Alternative/Additional entropy sources ==

=== Haveged ===

[http://www.issihosts.com/haveged/ Haveged] generates entropy based on [http://www.issihosts.com/haveged/flutter.html CPU flutter]. The entropy is buffered and fed into the entropy pool when write_wakeup_threshold is reached. Write a value (the number of bits) to it if you wish to change it:

{{Cmd|echo "1024" > /proc/sys/kernel/random/write_wakeup_threshold}}

Or change it via haveged:

{{Cmd|haveged -w 1024}}

Install [http://alpinelinux.org/apk/main/x86_64/haveged haveged], then start and set to autostart at boot:

{{Cmd|apk -U add haveged && rc-service haveged start && rc-update add haveged}}

[http://linux.die.net/man/8/haveged Further configuration] is possible however the defaults should work fine out of the box.

=== Other possibilities ===

Some other possibilites for entropy generation are:

*[http://www.vanheusden.com/te/ timer entropy daemon] - should provide on-demand entropy based on variances in timings of sleep command.

*[http://www.vanheusden.com/ved/ video entropy daemon] - requires a video4linux-device, gathers entropy by taking a couple of images and calculating the differences and then the entropy of that. Can be run on demand or as a cron job.

*[http://www.vanheusden.com/aed/ audio entropy daemon] - requires alsa development libraries and an audio device. Generates entropy by reading from audio device and de-baising data.

*[http://vladz.devzero.fr/guchaos.php GUChaos] - "Give Us Chaos" provides on-demand entropy, by retrieving random blocks of bytes from the [http://www.random.org/ Random.org] website, and transforms them with a [http://en.wikipedia.org/wiki/Substitution_cipher polynumeric substitution cipher] before adding them to /dev/random until the entropy pool is filled.

and hardware entropy generators such as:

*[http://www.entropykey.co.uk/ Entropy Key] - USB hardware entropy generator

It is also possible to replace /dev/random with [http://egd.sourceforge.net/ EGD, the Entropy Gathering Daemon], or to use this on systems that are not able to support /dev/random. However, this is not required (or recommended) under normal circumstances.

== Testing entropy with ENT ==

It is possible to [http://en.wikipedia.org/wiki/Randomness_test test] entropy to see how statistically random it is. Generally, such tests only reveal part of the picture, since some numbers can pass statistical entropy tests whilst they are not actually random. Failing a statistical randomness test is not a good indicator of course!

Make a folder for testing, and get hold of [http://www.fourmilab.ch/random/ ENT]:

<pre>
mkdir /tmp/test/make
cd /tmp/test/make
wget http://www.fourmilab.ch/random/random.zip
unzip random.zip
make
mv ./ent /tmp/test/
cd /tmp/test
</pre>

Create some random data. In this example we read from /dev/urandom:

<pre>dd if=/dev/urandom of=/tmp/test/urandomfile bs=1 count=16384</pre>

Run the ENT test against it:

{{Cmd|./ent /tmp/test/urandomfile}}

Try the same test whilst treating the data as a stream of bits and printing an account of character occurrences:

{{Cmd|./ent -b -c /tmp/test/urandomfile}}

Note any differences against the previous test.

I propose also generating larger streams of data (10's or 100's of MB) and testing against this too. Any repeating data or patterns (caused by a small/poor seed value for instance) will make spotting any weaknesses and a lack of randomness much easier across large amounts of data than across small amounts.

I also suggest running the test against known non-random files, so you may see that some tests show that such a file can have some characteristics of a random file, whilst completely failing other randomness tests.

Finally, once you are done testing with ENT, it's good practice to delete the working folder:

{{Cmd|rm -r /tmp/test/}}

=== Other tests ===

Other tests include [http://www.stat.fsu.edu/pub/diehard/ diehard] and [http://www.phy.duke.edu/~rgb/General/dieharder.php dieharder]

== Further reading ==

[http://rsmith.home.xs4all.nl/howto/fun-with-encryption-and-randomness.html visualising randomness]

[http://www.linuxfromscratch.org/hints/downloads/files/entropy.txt linux from scratch]

[http://blog.cloudflare.com/ensuring-randomness-with-linuxs-random-number-generator Cloudflare]

[https://tools.ietf.org/html/rfc4086 RFC 4086 - Randomness Requirements for Security]

[https://calomel.org/entropy_random_number_generators.html calomel.org]

[http://www.av8n.com/turbid/paper/turbid.htm Turbid]

[http://blog.cryptographyengineering.com/2012/02/random-number-generation-illustrated.html Random number generation: An illustrated primer]

[https://factorable.net/weakkeys12.extended.pdf Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices, PDF]

[http://www.pinkas.net/PAPERS/gpr06.pdf Analysis of the Linux Random Number Generator, PDF]

[http://cryptome.org/2014/03/eat-entropy-have-it.pdf How to Eat Your Entropy and Have it Too — Optimal Recovery Strategies for Compromised RNGs, PDF]

[http://eprint.iacr.org/2013/338.pdf Security Analysis of Pseudo-Random Number Generators with Input: /dev/random is not Robust, PDF]

[[Category:Server]]

SLiM

2014-11-05T14:57:14Z

Ginjachris: added warning that SLiM appears to be abandoned

[http://slim.berlios.de/index.php SLiM] is a Simple Login Manager (also known as a display manager) which is lightweight and simple to configure.

{{Warning|The SLiM project appears to have been abandoned and the [http://slim.berlios.de/ project homepage] is down}}

== Install ==

Simply add the {{Pkg|slim}} package with:
{{Cmd|apk add slim}}
I should imagine you'd also want some kind of desktop installed too, like [[Gnome Setup|Gnome]] or [[XFCE Setup|XFCE]]

== Configure & Test ==

The SLiM configuration file is at <code>/etc/slim.conf</code> and it is heavily commented, so I'll not add any info about it here unless asked to (in the discussion function for instance). Before making any changes it is recommended to backup the default configuration file with:
{{Cmd|cp /etc/slim.conf /etc/slim.conf.original}}

Then you can modify <code>/etc/slim.conf</code> and easily copy the default configuration back if you run into trouble:
{{Cmd|cp /etc/slim.conf.original /etc/slim.conf}}

To immediately test slim, do {{Cmd|rc-service slim start}} and you should be presented with a login screen, branded for Alpine linux!

Login with your normal user credentials (avoid using a desktop as root) and you should reach your desktop.

Once you've tested it works, start SLiM at the default runlevel:
{{Cmd|rc-update add slim}}

Note: You should disable any other display manager you have running to prevent them both launching. For example, to prevent lxdm from starting at boot use:
{{Cmd|rc-update del lxdm}}

== Extra Login Commands ==
When on the SLiM login screen, you can use:
* <code>exit</code> as a username to return to a shell prompt
* <code>reboot</code> as a username and the root password to reboot the machine
* <code>halt</code> as a username and the root password to power down the machine

== Troubleshooting ==

If you are using a .xinitrc file (usually located at <code>~/.xinitrc</code>, slim will read from this and you will need to ensure you have a line to execute your desktop environment. This is usually the last line of the file. For example:
<pre>....
exec startxfce4
</pre>
if you are using an [[XFCE Setup|XFCE desktop]], or:
<pre>....
exec gnome-session
</pre>
if using [[Gnome Setup|Gnome]].

If you don't do this, or you make a mistake with your typing, you'll probably get an error like <code>failed to execute login command</code>

== Themes ==

Simply add the {{Pkg|slim-theme}} package with:
{{Cmd|apk add slim-themes}}

All theme which are available on your system are located at <code>/usr/share/slim/themes</code>
{{Cmd|ls /usr/share/slim/themes}}

You need to modify <code>/etc/slim.conf</code> to change the theme:
{{Cmd|sudo vi /etc/slim.conf}}

Search for <code>current_theme</code> and choose one of the available themes.

== Further Information ==

* [http://slim.berlios.de/index.php SLiM Homepage]
* [http://slim.berlios.de/manual.php SLiM Manual]
* [https://wiki.archlinux.org/index.php/SLiM Arch Linux wiki entry]

Lighttpd Advanced security

2014-10-21T09:32:25Z

Ginjachris: minor spelling corrections after added lighttpd poodle vulnerability section

For higher security [[Lighttpd]] can be configured to allow https access.

==Generate Certificate and Keys==
Either generate the public key and certificate and private key using {{Pkg|openssl}}, or by using the ones generated by installing [[Alpine_Configuration_Framework_Design| ACF]]. You don't need to do both, just do one or the other. The former method, with OpenSSL, is preferred since it gives greater control.

===Generate self-signed certificates with openssl ===
To generate certificates, openssl is needed.

{{Cmd|apk add openssl}}

Change to the lighttpd configuration directory

{{Cmd|cd /etc/lighttpd}}

With the command below the self-signed certificate and key pair are generated. A 2048 bit key is the minimum recommended at the time of writing, so we use '-newkey rsa:2048' in the command. Change to suit your needs. Answer all questions.

{{Cmd|openssl req -newkey rsa:2048 -x509 -keyout server.pem -out server.pem -days 365 -nodes}}

Adjust the permissions

{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

=== Generate self-signed certificates with acf ===

Install the [[Alpine_Configuration_Framework_Design| ACF]]

{{Cmd|setup-acf}}

Copy the generated certificate to the lighttpd configuration directory.

{{Cmd|mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server.pem}}

Adjust the permissions

{{Cmd|chown root:root /etc/lighttpd/server.pem}}
{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

mini_http is no longer needed.

{{Cmd|/etc/init.d/mini_httpd stop && rc-update del mini_httpd}}

Removing the mini_http package

{{Cmd|apk del mini_httpd}}

==Configure Lighttpd==
The configuration of lighttpd needs to be modified.

{{Cmd|nano /etc/lighttpd/lighttpd.conf}}

Uncomment this section and adjust the path so 'ssl.pemfile' points to where our cert/key pair is stored. Or copy the example below into your configuration file if you saved it to /etc/lighttpd/server.pem.
<pre>
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"
</pre>

You'll also want to set the server to listen on port 443. Replace this:
server.port = 80
with this:
server.port = 443

Restart lighttpd

{{Cmd|rc-service lighttpd restart}}

== Security ==

=== BEAST attack, CVE-2011-3389 ===
To help mitigate the BEAST attack add the following to your configuration:

#### Mitigate BEAST attack:

# A stricter base cipher suite. For details see:
# http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-3389
# or
# http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3389

ssl.cipher-list = "ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM"
#
# Make the server prefer the order of the server side cipher suite instead of the client suite.
# This is necessary to mitigate the BEAST attack (unless you disable all non RC4 algorithms).
# This option is enabled by default, but only used if ssl.cipher-list is set.
ssl.honor-cipher-order = "enable"

# Mitigate CVE-2009-3555 by disabling client triggered renegotiation
# This option is enabled by default.
#
ssl.disable-client-renegotiation = "enable"
#

=== Perfect Forward Secrecy (PFS) ===

[https://en.wikipedia.org/wiki/Perfect_forward_secrecy Perfect Forward Secrecy] isn't perfect, but what it does mean is that an adversary who gains the private key of a server does not have the ability to decrypt every encrypted SSL/TLS session. Without it, an adversary can simply obtain the private key of a server and decrypt and and all SSL/TLS sessions using that key. This is a major security and privacy concern and so using PFS is probably a good idea long term. It means that every session would have to be decrypted individually, regardless of the state (whether obtained by the adversary or otherwise).

Ultimately when choosing SSL/TLS ciphers it is the usual chose of security or usability? Increasing one usually decreases the other. Nonetheless, an example to prevent the BEAST attack and offer PFS is:

<pre>
ssl.cipher-list = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-RC4-SHA:ECDHE-RSA-RC4-SHA:ECDH-ECDSA-RC4-SHA:ECDH-RSA-RC4-SHA:ECDHE-RSA-AES256-SHA:RC4-SHA"
</pre>

[https://raymii.org/s/tutorials/Pass_the_SSL_Labs_Test_on_Lighttpd_%28Mitigate_the_CRIME_and_BEAST_attack_-_Disable_SSLv2_-_Enable_PFS%29.html Source]

=== POODLE attack (CVE-2014-3566) ===

In light of the recent [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3566 POODLE] findings, it's advisable to wherever possible turn off support for SSLv3. This is quite simple, you can just append the following to your cipher list to explicitly disable SSLv3 support:

<pre>
:!SSLv3
</pre>

== Other configurations ==
The following are example configs, they will likely need to be modified to suite your particular setup. Nonetheless they should provide an indication of how to implement the relevant configuration options.

=== redirecting HTTP to HTTPS ===
Any requests to the server via HTTP (TCP port 80 by default) will be redirected to HTTPS (port 443):

<pre>
server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Ensure mod_redirect is enabled!
server.modules = (
"mod_redirect",
)

$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}

$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
## Make sure the line above points to your SSL cert/key pair!
}

</pre>

=== Serving both HTTP and HTTPS requests ===
Simple, just add in the SSL server port, enable the SSL engine and point to the relevant SSL cert/key pair:

<pre>

server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Below is HTTPS setup. Make sure to point at relevant cert/key pair for HTTPS to work!
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
}
</pre>

== More details ==
* [http://redmine.lighttpd.net/wiki/1/Docs:SSL Lighttpd documentation]

[[Category:Server]]
[[Category:Security]]

Lighttpd Advanced security

2014-10-21T09:28:44Z

Ginjachris: /* Perfect Forward Secrecy (PFS) */

For higher security [[Lighttpd]] can be configured to allow https access.

==Generate Certificate and Keys==
Either generate the public key and certificate and private key using {{Pkg|openssl}}, or by using the ones generated by installing [[Alpine_Configuration_Framework_Design| ACF]]. You don't need to do both, just do one or the other. The former method, with OpenSSL, is preferred since it gives greater control.

===Generate self-signed certificates with openssl ===
To generate certificates, openssl is needed.

{{Cmd|apk add openssl}}

Change to the lighttpd configuration directory

{{Cmd|cd /etc/lighttpd}}

With the command below the self-signed certificate and key pair are generated. A 2048 bit key is the minimum recommended at the time of writing, so we use '-newkey rsa:2048' in the command. Change to suit your needs. Answer all questions.

{{Cmd|openssl req -newkey rsa:2048 -x509 -keyout server.pem -out server.pem -days 365 -nodes}}

Adjust the permissions

{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

=== Generate self-signed certificates with acf ===

Install the [[Alpine_Configuration_Framework_Design| ACF]]

{{Cmd|setup-acf}}

Copy the generated certificate to the lighttpd configuration directory.

{{Cmd|mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server.pem}}

Adjust the permissions

{{Cmd|chown root:root /etc/lighttpd/server.pem}}
{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

mini_http is no longer needed.

{{Cmd|/etc/init.d/mini_httpd stop && rc-update del mini_httpd}}

Removing the mini_http package

{{Cmd|apk del mini_httpd}}

==Configure Lighttpd==
The configuration of lighttpd needs to be modified.

{{Cmd|nano /etc/lighttpd/lighttpd.conf}}

Uncomment this section and adjust the path so 'ssl.pemfile' points to where our cert/key pair is stored. Or copy the example below into your configuration file if you saved it to /etc/lighttpd/server.pem.
<pre>
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"
</pre>

You'll also want to set the server to listen on port 443. Replace this:
server.port = 80
with this:
server.port = 443

Restart lighttpd

{{Cmd|rc-service lighttpd restart}}

== Security ==

=== BEAST attack, CVE-2011-3389 ===
To help mitigate the BEAST attack add the following to your configuration:

#### Mitigate BEAST attack:

# A stricter base cipher suite. For details see:
# http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-3389
# or
# http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3389

ssl.cipher-list = "ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM"
#
# Make the server prefer the order of the server side cipher suite instead of the client suite.
# This is necessary to mitigate the BEAST attack (unless you disable all non RC4 algorithms).
# This option is enabled by default, but only used if ssl.cipher-list is set.
ssl.honor-cipher-order = "enable"

# Mitigate CVE-2009-3555 by disabling client triggered renegotiation
# This option is enabled by default.
#
ssl.disable-client-renegotiation = "enable"
#

=== Perfect Forward Secrecy (PFS) ===

[https://en.wikipedia.org/wiki/Perfect_forward_secrecy Perfect Forward Secrecy] isn't perfect, but what it does mean is that an adversary who gains the private key of a server does not have the ability to decrypt every encrypted SSL/TLS session. Without it, an adversary can simply obtain the private key of a server and decrypt and and all SSL/TLS sessions using that key. This is a major security and privacy concern and so using PFS is probabky a good idea long term. It means that every session would have to be decrypted individually, regardless of the state (whether obtained by the adversary or otherwise).

Ultimately when choosing SSl/TLS ciphers it is the usual chose of security or usabililty? Increasing one usually decreases the other. Nonetheles, an example to prevent the BEAST attack and offer PFS is:

<pre>
ssl.cipher-list = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-RC4-SHA:ECDHE-RSA-RC4-SHA:ECDH-ECDSA-RC4-SHA:ECDH-RSA-RC4-SHA:ECDHE-RSA-AES256-SHA:RC4-SHA"
</pre>

[https://raymii.org/s/tutorials/Pass_the_SSL_Labs_Test_on_Lighttpd_%28Mitigate_the_CRIME_and_BEAST_attack_-_Disable_SSLv2_-_Enable_PFS%29.html Source]

=== POODLE attack (CVE-2014-3566) ===

In light of the recent [https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2014-3566 POODLE] findings, it's advisable to wherever possible turn off support for SSLv3. This is quite simple, you can just append the following to your cipher list to explicitly disable SSLv3 support:

<pre>
:!SSLv3
</pre>

== Other configurations ==
The following are example configs, they will likely need to be modified to suite your particular setup. Nonetheless they should provide an indication of how to implement the relevant configuration options.

=== redirecting HTTP to HTTPS ===
Any requests to the server via HTTP (TCP port 80 by default) will be redirected to HTTPS (port 443):

<pre>
server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Ensure mod_redirect is enabled!
server.modules = (
"mod_redirect",
)

$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}

$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
## Make sure the line above points to your SSL cert/key pair!
}

</pre>

=== Serving both HTTP and HTTPS requests ===
Simple, just add in the SSL server port, enable the SSL engine and point to the relevant SSL cert/key pair:

<pre>

server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Below is HTTPS setup. Make sure to point at relevant cert/key pair for HTTPS to work!
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
}
</pre>

== More details ==
* [http://redmine.lighttpd.net/wiki/1/Docs:SSL Lighttpd documentation]

[[Category:Server]]
[[Category:Security]]

Setting up Explicit Squid Proxy

2014-07-18T12:04:55Z

Ginjachris: amended transparent proxy definition re: authentication

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server is not usually involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of. There are however, ways around this, which usually involve redirecting the client to a login page (or captive portal).

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation apears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames enabled
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

User:Ginjachris

2014-07-18T11:46:55Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some crazy Drum 'n' Bass:

[http://grooveshark.com/s/Doorway+Gridlock+Echo+Remix/aGkez?src=5 'Doorway' by Usual Suspects (Gridlock & Echo remix)]

[http://grooveshark.com/s/No+Test/3GHSp1?src=5 'No test' by Distorted Minds]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server
* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

Setting up Explicit Squid Proxy

2014-07-11T10:13:06Z

Ginjachris: /* Amend /etc/squid/squid.conf */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server cannot be involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation apears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

The decision you're making with the 'sslproxy_cert_error' (and potentially the 'sslproxy_flags') option is to either close the connection when a certificate error is encountered (such as a self-signed, untrusted certificate is presented), or to pass certificate errors onto the client to allow them to make the choice about the site and whether or not to trust the certificate.

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames enabled
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

Raid Administration

2014-07-08T11:29:02Z

Ginjachris: /* General recommendations */ corrected minor error re: spare disks

== Introduction ==

Whilst there are articles on RAID installation (see [[ISCSI Raid and Clustered File Systems|1]], [[High performance SCST iSCSI Target on Linux software Raid|2]], [[Linux iSCSI Target (TCM)|3]], [[Setting up a software RAID1 array|4]], [[Setting up a /var partition on software IDE raid1|5]], [[Setting up disks manually|6]], [[Ensuring that /var is correctly mounted on HDD|7]] for example) to various degrees, this article is designed to provide practical information on RAID administration, regardless of RAID type used or installation method.

This article is of course using linux software RAID, also known as ''md'' after the controlling process, which is controlled by the <code>mdadm</code> command.

For the purposes of this example, we will create a [https://en.wikipedia.org/wiki/RAID#RAID_1 RAID 1] array across /dev/sda and /dev/sdb using the <code>setup-alpine</code> script (more specifically the [[Alpine Setup Scripts#RAID|setup-disk script]]) and then add /dev/sdc to the array after installation. This will add it as a hot spare which will be used if one of the other drives becomes degraded. Alternatively the drive can immediately be added to the RAID array (as explained in the optional steps).
The instructions in this article should work regardless of whether you are using [https://en.wikipedia.org/wiki/RAID#RAID_1 RAID 1] or [https://en.wikipedia.org/wiki/RAID#RAID_5 RAID 5] and whether you have [[Setting up disks manually|setup your disks manually]] or with the [[Install to disk|setup script]], unless stated otherwise.

In this example /dev/sda, /dev/sdb and /dev/sdc are all virtual 2GB disks on a VMware machine (it doesn't matter that it's a VM, the same process applies to a real machine with physical disks of larger sizes).

In our example, all disks are available (present) at the time of installation, however /dev/sdc could be added at a later time; this has no impact on the procedure described other than having to physically add the disk.

== Initial setup ==

Install with <code>setup-alpine</code> and pass the relevant disks to [[Alpine setup scripts#setup-disk|setup-disk]] (in our case <code>sda sdb</code>) and use installation method <code>sys</code>.

This should create the following disk setup (it will differ in your setup since values of course depend on drive size):
<pre>
md0 composed of /dev/sda1 and /dev/sdb1 ~100MB mounted as /boot

md1 composed of /dev/sda2 and /dev/sdb2 ~512MB as /swap

md2 composed of /dev/sda3 and /dev/sdb3 ~1400MB mounted as /
</pre>
As you can see, we have redundancy across the two drives /dev/sda and /dev/sdb.

== Review ==

Run <code>df -h</code> and observe that the RAID arrays are mounted, not the disk partitions as usual.

To see information on the current RAID partitions use the query option:
<pre>
mdadm --query /dev/md0
</pre>
or for more information use the detail option
<pre>
mdadm --detail /dev/md1
</pre>
After the initial setup, if you haven't added the third drive (/dev/sdc) now is the time to poweroff and physically add it to the machine.

== Add devices to the array ==

Now, let's add /dev/sdc to the RAID array.

=== Copy partition table ===

First, copy the partition table from an existing drive to the new drive. Be '''very''' careful with the dd command and ensure you are copying from/to the correct place! {{Note|for [[Setting up LVM on GPT-labeled disks|GPT]] partitioning, which you might have used if you've setup your disks manually, this dd command is unlikely to work since [https://en.wikipedia.org/wiki/GUID_Partition_Table GPT] stores its information differently}}
<pre>
dd if=/dev/sda of=/dev/sdc bs=512 count=1
</pre>
Ensure this worked correctly by comparing the output of sfdisk, they should be identical:
<pre>
sfdisk --dump /dev/sda
sfdisk --dump /dev/sdc
</pre>

=== Add devices ===

Now add the partitions of the new disk to the relevant RAID arrays. Be sure to add the correct partitions to the correct arrays!
<pre>
mdadm /dev/md0 -a /dev/sdc1
mdadm /dev/md1 -a /dev/sdc2
mdadm /dev/md2 -a /dev/sdc3
</pre>
You should see something like <code>mdadm: added /dev/sdc1</code> if the command is successful. The '''-a''' flag is for '''add'''.

Now see how the output of the query command has changed from earlier:
<pre>
mdadm --query /dev/md0
mdadm --query /dev/md1
mdadm --query /dev/md2
</pre>
You should see we still have two devices in each array, plus now we have a spare. A spare is an inactive device that is a member of the array; it will only be used if one of the other devices fails. If this is good enough for you, you're done!

=== Grow the array (optional) ===

Otherwise you can take the optional step to add the 'spare' device so it immediately becomes part of the array. Since we're using RAID 1 in our example this effectively gives us ''another'' backup of all data:
<pre>
mdadm --grow /dev/md0 -n 2
</pre>
Should give you something like <code>mdamd: /dev/md0: no change requested</code>. This is because we already have <code>-n 2</code> set (so we use 2 devices in the array). Obviously the '''--grow''' flag is used to '''grow''' the array and increase (or [[Raid_Administration#Change_device_count_.28optional.29|decrease]]) the number of devices in the array. Let's increase the value and bring in the additional device to the array:
<pre>
mdadm --grow /dev/md0 -n 3
</pre>
You should see something like <code>raid_disks for /dev/md0 set to 3</code> if successful. '''-n 3''' specifies that there should be three ''active'' devices in the array. There can still be additional ''spare'' devices if you add more and do not grow the array.

Review the output of <code>mdadm --query /dev/md0</code> or <code>mdadm --detail /dev/md0</code> again to confirm it worked. Don't worry if you see something about 'spare rebuilding' - this is normal and will be replaced with a state of 'active sync' once data copying is complete.

Ensure to add the other devices (partitions) to the arrays by increasing the device count for the other arrays (otherwise they will remain as spares and not be immediately utilised):
<pre>
mdadm --grow /dev/md1 -n 3
mdadm --grow /dev/md2 -n 3
</pre>

== Remove devices ==

To remove a failed device use the following; remember you will need to remove all the partitions of the failing drive (devices) from the relevant RAID arrays. In our example, we will mark the partitions of /dev/sdb as failed and remove them from the array:
<pre>
mdadm /dev/md0 -f /dev/sdb1 -r /dev/sdb1
mdadm /dev/md1 -f /dev/sdb2 -r /dev/sdb2
mdadm /dev/md2 -f /dev/sdb3 -r /dev/sdb3
</pre>
Check the output of <code>mdadm --detail /dev/md2</code> and see how the device is marked as 'removed'.
The '''-f''' flag is used to mark a device as '''failed''' and '''-r''' is used to '''remove''' a device from the array.

To add a removed device back in, ensure it's partitioned correctly (replace the drive if necessary and copy over the partition table from a known good drive) and then simply add it back in again:
<pre>
mdadm /dev/md2 -a /dev/sdb3
</pre>
(repeat for other partitions as appropriate).

=== Change device count (optional) ===

To entirely remove the device from the array (assuming you are not going to add it back later for instance) amend the device count again, this will remove it from the list so it no longer shows as 'removed' and we are back to two devices in the array:
<pre>
mdadm --grow /dev/md0 -n 2
mdadm --grow /dev/md1 -n 2
mdadm --grow /dev/md2 -n 2
</pre>
If you do need to add disks back in again, you need to add them as spares (<code>mdadm /dev/md0 -a /dev/sdb1</code> etc) and then change the device count if you wish to make the device active, as per the section on [[Raid_Administration#Add_devices_to_the_array|adding devices]].

=== Zero the superblock ===

Zeroing the superblock is important if you intend to take a disk from an array and add it to another array, for example on another machine. Zeroing the superblock will prevent the RAID array from becoming confused about which array it should be building; leaving the old superblock information on a disk means it will try to read this old superblock information and this can cause all manner of headaches. So, to remove the superblock from a disk so you can use it elsewhere, simply use the <code>--zero-superblock</code> option. To continue from our example above:

<pre>
mdadm --zero-superblock /dev/sdb1
mdadm --zero-superblock /dev/sdb2
mdadm --zero-superblock /dev/sdb3
</pre>

drive /dev/sdb can then be removed and added to another RAID array without causing issues.

== General recommendations ==

When making use of RAID arrays best practice is to have one more disk than is required and added as a spare. This immediately provides some form of redundancy. Remember that for RAID 1 you cannot go below 2 disks (well you can run on one disk, known as degraded mode, but ''this is best avoided at all costs'') and with RAID 5 you cannot go below 3 disks. In short, if you are using RAID, have a ''spare'' device configured.

Disks cost money, but the data on those disks is often priceless!

It's a good idea to have a test environment to play around with RAID ''before'' implementing it in a production environment. Worst case, setup a [https://virtualbox.org/ VirtualBox] host and run an Alpine VM and play around with that, prior to using a production system.

== Further information ==

[http://linux.die.net/man/8/mdadm man mdadm]

[https://en.wikipedia.org/wiki/RAID RAID on wikipedia]

[https://raid.wiki.kernel.org/index.php/Linux_Raid Linux RAID wiki at kernel.org]

Alpine Package Keeper

2014-07-03T13:18:44Z

Ginjachris: /* Info on Packages */ ->added 'listing installed packages'

Because Alpine Linux is designed to run from RAM, package management involves two phases:
* Installing / Upgrading / Deleting packages on a running system
* Restoring a system to a previously configured state (e.g. after reboot), including all previously installed packages and locally modified configuration files. '''(RAM-Based Installs Only)'''
 
'''apk''' is the tool used to install, upgrade, or delete software on a running sytem. 
'''lbu''' is the tool used to capture the data necessary to restore a system to a previously configured state.

This page documents the [http://git.alpinelinux.org/cgit/apk-tools.git apk tool] - See the [[Alpine_local_backup|Alpine Local Backup page]] for the lbu tool.

= Overview =

The '''apk''' tool has the following applets:

{|
| [[#Add a Package|add]]
| Add new packages to the running system
|-
| [[#Remove a Package|del]]
| Delete packages from the running system
|-
| fix
| Attempt to repair or upgrade an installed package
|-
| [[#Update the Package list|update]]
| Update the index of available packages
|-
| [[#Info on Packages|info]]
| Prints information about installed or available packages
|-
| [[#Search for Packages|search]]
| Search for packages or descriptions with wildcard patterns
|-
| [[#Upgrade a Running System|upgrade]]
| Upgrade the currently installed packages
|-
| [[#Cache Maintenance|cache]]
| Maintenance operations for locally cached package repository
|-
| version
| Compare version differences between installed and available packages
|-
| index
| create a repository index from a list of packages
|-
| fetch
| download (but not install) packages
|-
| audit
| List changes to the file system from pristine package install state
|-
| verify
| Verify a package signature
|}

= Packages and Repositories =

Software packages for Alpine Linux are digitally signed tar.gz archives containing the programs, configuration files, and dependency metadata. They have the extension <code>.apk</code>, and are often called "a-packs"

The packages are stored in one or more ''repositories''. A repository is simply a directory with a collection of *.apk files. The directory must include a special index file, named {{Path|APKINDEX.tar.gz}} to be considered a repository.

The '''apk''' utility can install packages from multiple repositories. The list of repositories to check is stored in {{Path|/etc/apk/repositories}}, one repository per line. If you booted from USB stick ({{Path|/media/sda1}}) or CD-ROM ({{Path|/media/cdrom}}), your repository file probably looks something like this:

{{Cat|/etc/apk/repositories|/media/sda1/apks/}}

In addition to local repositories, the '''apk''' utility uses '''busybox wget''' to fetch packages using ''http:'', ''https:'' or ''ftp:'' protocols. The following is a valid repository file:

{{Cat|/etc/apk/repositories|
/media/sda1/apks
http://dl-3.alpinelinux.org/alpine/v2.6/main
https://dl-3.alpinelinux.org/alpine/v2.6/main
ftp://dl-3.alpinelinux.org/alpine/v2.6/main
}}

{{Note|Currently there are no public https or ftp repositories. The protocols are available for local repositories.}}

== Repository pinning ==

You can specify additional "tagged" repositories in {{Path|/etc/apk/repositories}}:

{{Cat|/etc/apk/repositories|
http://nl.alpinelinux.org/alpine/v2.6/main
@edge http://nl.alpinelinux.org/alpine/edge/main
@testing http://nl.alpinelinux.org/alpine/edge/testing
}}

After which you can "pin" dependencies to these tags using:

{{cmd|apk add stableapp newapp@edge bleedingapp@testing}}

Apk will now by default only use the untagged repositories, but adding a tag to specific package:

1. will prefer the repository with that tag for the named package, even if a later version of the package is available in another repository

2. ''allows'' pulling in dependencies for the tagged package from the tagged repository (though it ''prefers'' to use untagged repositories to satisfy dependencies if possible)

= Update the Package list =

Remote repositories change as packages are added and upgraded. To get the latest list of available packages, use the ''update'' command. The command downloads the {{Path|APKINDEX.tar.gz}} from each repository and stores it in the local cache, typically {{Path|/var/lib/apk/}} or {{Path|/etc/apk/cache/}}.

{{Cmd|apk update}}



{{Tip|If using remote repositories, it is a good idea to do an '''update''' just before doing an '''add''' or '''upgrade''' command. That way you know you are using the latest software available.}}

= Add a Package =

Use '''add''' to install packages from a repository. Any necessary dependencies are also installed. If you have multiple repositories, the '''add''' command installs the newest package.

{{Cmd|apk add openssh
apk add openssh openntp vim}}

If you only have the main repository enabled in your configuration, apk will not include packages from the other repositories. To install a package from the edge/testing repository without changing your repository configuration file, use the command below. This will tell apk to use that particular repository.

{{cmd|apk add cherokee --update-cache --repository http://dl-3.alpinelinux.org/alpine/edge/testing/ --allow-untrusted}}

{{Note|Be careful when using third-party or the testing repository. Your system can go down.}}

= Remove a Package =
Use '''del''' to remove a package (and dependencies that are no longer needed.)

{{cmd|apk del openssh
apk del openssh openntp vim}}

= Upgrade a Running System =

To upgrade ''all'' the packages of a running system, use '''upgrade''':

{{cmd|apk update
apk upgrade
}}

To upgrade ''only a few'' packages, use the '''add''' command with the ''-u'' or ''--upgrade'' option:

{{cmd|apk update
apk add --upgrade busybox
}}

{{Note|Remember that when you reboot your machine, the remote repository will not be available until after networking is started. This means packages newer than your local boot media will likely not be installed after a reboot. To make an "upgrade" persist over a reboot, use a [[#Local Cache|local cache]].}}

= Search for Packages =
The '''search''' command searches the repository Index files for installable packages.

Examples:
* To list all packages available, along with their descriptions: {{cmd|apk search -v}}
* To list all packages are part of the ACF system: {{cmd|apk search -v 'acf*' }}
* To list all packages that list NTP as part of their description, use the ''-d'' or ''--description'' option: {{cmd|apk search -v --description 'NTP' }}

= Info on Packages =

The '''info''' command provides information on the contents of packages, their dependencies, and which files belong to a package.

For a given package, each element can be chosen (for example, ''-w'' to show just the webpage information); or all information is displayed with the ''-a'' command.

Example: {{cmd|apk info -a zlib}}

'''zlib-1.2.5-r1 description:'''
A compression/decompression Library

'''zlib-1.2.5-r1 webpage:'''
<nowiki>http://zlib.net</nowiki>

'''zlib-1.2.5-r1 installed size:'''
94208

'''zlib-1.2.5-r1 depends on:'''
libc0.9.32

'''zlib-1.2.5-r1 is required by:'''
libcrypto1.0-1.0.0-r0
apk-tools-2.0.2-r4
openssh-client-5.4_p1-r2
openssh-5.4_p1-r2
libssl1.0-1.0.0-r0
freeswitch-1.0.6-r6
atop-1.25-r0

'''zlib-1.2.5-r1 contains:'''
lib/libz.so.1.2.5
lib/libz.so.1
lib/libz.so

'''zlib-1.2.5-r1 triggers:'''

As shown in the example you can determine
* The '''description''' of the package (''-d'' or ''--description'')
* The '''webpage''' where the application is hosted (''-w'' or ''--webpage'')
* The '''size''' the package will require once installed (in bytes) (''-s'' or ''--size'')
* What packages are required to use this one ('''depends''') (''-R'' or ''--depends'')
* What packages require this one to be installed ('''required by''') (''-r'' or ''--rdepends'')
* The '''contents''' of the package, that is, which files it installs (''-L'' or ''--contents'')
* Any '''triggers''' this package sets. (''-t'' or ''--triggers'') Listed here are directories that are watched; if a change happens to the directory, then the trigger script is run at the end of the apk add/delete. For example, doing a depmod once after installing all packages that add kernel modules.

{{Tip|The '''info''' command is also useful to determine which package a file belongs to. For example: {{cmd|apk info --who-owns /sbin/lbu}} will display

/sbin/lbu is owned by alpine-conf-x.x-rx
}}

== Listing installed packages ==

To list all installed packages, use:

<pre>apk info</pre>

To list all installed packages in alphabetical order, with a description of each, do:

<pre>apk -vv info|sort</pre>

= Additional apk Commands =
In progress...

= Local Cache =

{{:Local_APK_cache}}

= Advanced APK Usage =

== Holding a specific package back ==

In certain cases, you may want to upgrade a system, but keep a specific package at a back level. It is possible to add "sticky" or versioned dependencies. For instance, to hold the ''asterisk'' package to the 1.6.2 level or lower:
{{cmd|1=apk add asterisk=1.6.0.21-r0}}
or
{{cmd|apk add 'asterisk<1.6.1'}}

after which a {{cmd|apk upgrade}}

will upgrade the entire system, keeping the asterisk package at the 1.6.0 or lower level

To later upgrade to the current version,

{{cmd|apk add 'asterisk>1.6.1'}}

[[Category:Package Manager]]

Entropy and randomness

2014-07-02T18:09:05Z

Ginjachris: removed reference to wipe

== Introduction ==

[https://en.wikipedia.org/wiki/Entropy_%28computing%29 Entropy] is described as 'a numerical measure of the uncertainty of an outcome' and is often associated with chaos or disorder however is often more simply called [https://en.wikipedia.org/wiki/Randomness randomness].

It is important for a secure operating system to have sufficient quantities of entropy available for various crypotographic and non-cryptographic purposes, such as:

* Generation of cryptographic keys

* Address Space Layout Randomisation ([http://en.wikipedia.org/wiki/PaX#Address_space_layout_randomization ASLR]) - used by default in Alpine of course ;)

* TCP port randomisation ([https://en.wikipedia.org/wiki/Network_address_translation NAT], outbound connection)

* [https://en.wikipedia.org/wiki/Transmission_Control_Protocol#Reliable_transmission TCP sequence number] selection (see [https://en.wikipedia.org/wiki/TCP_sequence_prediction_attack this too)]

* Writing random files for testing network functionality and throughput

* Overwriting hard disks prior to reuse or resale or encryption

Entropy is contained within a '''pool''', which draws its entropy from various '''sources'''. To view the current amount of entropy in the pool:

{{Cmd|more /proc/sys/kernel/random/entropy_avail}}

To view the maximum limit of entropy that the pool can hold:

{{Cmd|more /proc/sys/kernel/random/poolsize}}

On a standard system the limit is 4096 bits (512 bytes). The [https://grsecurity.net/ gr-sec] patch used on Alpine increases this limit to 16384 bits (2048 bytes).
Entropy is added to the pool in bits from various sources, "the relative number of unknown bits per event is roughly 8/keyboard, 12/mouse, 3/disk, 4/interrupt" [http://www.issihosts.com/haveged/history.html#intro source] meaning that on a headless server (without mouse and keyboard attached), which ironically is often a system requiring the most entropy, entropy generation is somewhat limited.

The entropy from the pool can be accessed in two ways by default:

'''/dev/random''' - This is a [https://en.wikipedia.org/wiki/Blocking_%28computing%29 blocking] resource, so it will use available entropy from the pool. If more entropy is required than is available, the process will wait until more entropy is available in the pool. Due to this behaviour, /dev/random is best used where small amounts of high quality randomness are required, such as for cryptographic keys.

'''/dev/urandom''' - Is a non-blocking resource. It uses a seed value from the same entropy pool as /dev/random and therefore, if little entropy is available in the pool, it is recommended not to use /dev/urandom until more entropy is made available in the pool. It runs the seed value through an algorithm and so is a [http://en.wikipedia.org/wiki/Pseudo-random_number_generator pseudo-random number generator], operating much faster than /dev/random. /dev/urandom is best used for non-cryptographic purposes such as overwriting disks.

Writing to /dev/random or /dev/urandom will update the entropy pool with the data written, but this will not result in a higher entropy count. This means that it will impact the contents read from both files, but it will not make reads from /dev/random faster.
For more information see the [http://www.manpagez.com/man/4/random/ random manpage]

It is generally recommended wherever entropy is used heavily to supply additional entropy sources; some possibilities are below. Adding more sources of entropy to feed into the pool is a good idea. It makes an attackers job more difficult, because there will be more sources they have to gain control over (or at the very least observe at source), and adding more sources of entropy, even weak ones, can only result in higher entropy.

If you are desperate for more entropy and are working on a headless server with no internet connection, you could try generating some via disk activity. Just don't expect any miracles! Here's an example:

<pre>dd if=/dev/zero of=/var/tmp/tempfile bs=1M count=200 && find / -size +1k && ls -R / && rm /var/tmp/tempfile && sync</pre>

If your server is a 'run-from-ram' setup and so you have no disks to create churn but require more entropy, it is strongly recommended to add alternative entropy sources as discussed below.

== Alternative/Additional entropy sources ==

=== Haveged ===

[http://www.issihosts.com/haveged/ Haveged] generates entropy based on [http://www.issihosts.com/haveged/flutter.html CPU flutter]. The entropy is buffered and fed into the entropy pool when write_wakeup_threshold is reached. Write a value (the number of bits) to it if you wish to change it:

{{Cmd|echo "1024" > /proc/sys/kernel/random/write_wakeup_threshold}}

Or change it via haveged:

{{Cmd|haveged -w 1024}}

Install [http://alpinelinux.org/apk/main/x86_64/haveged haveged], then start and set to autostart at boot:

{{Cmd|apk -U add haveged && rc-service haveged start && rc-update add haveged}}

[http://linux.die.net/man/8/haveged Further configuration] is possible however the defaults should work fine out of the box.

=== Other possibilities ===

Some other possibilites for entropy generation are:

*[http://www.vanheusden.com/te/ timer entropy daemon] - should provide on-demand entropy based on variances in timings of sleep command.

*[http://www.vanheusden.com/ved/ video entropy daemon] - requires a video4linux-device, gathers entropy by taking a couple of images and calculating the differences and then the entropy of that. Can be run on demand or as a cron job.

*[http://www.vanheusden.com/aed/ audio entropy daemon] - requires alsa development libraries and an audio device. Generates entropy by reading from audio device and de-baising data.

*[http://vladz.devzero.fr/guchaos.php GUChaos] - "Give Us Chaos" provides on-demand entropy, by retrieving random blocks of bytes from the [http://www.random.org/ Random.org] website, and transforms them with a [http://en.wikipedia.org/wiki/Substitution_cipher polynumeric substitution cipher] before adding them to /dev/random until the entropy pool is filled.

and hardware entropy generators such as:

*[http://www.entropykey.co.uk/ Entropy Key] - USB hardware entropy generator

It is also possible to replace /dev/random with [http://egd.sourceforge.net/ EGD, the Entropy Gathering Daemon], or to use this on systems that are not able to support /dev/random. However, this is not required (or recommended) under normal circumstances.

== Testing entropy with ENT ==

It is possible to [http://en.wikipedia.org/wiki/Randomness_test test] entropy to see how statistically random it is. Generally, such tests only reveal part of the picture, since some numbers can pass statistical entropy tests whilst they are not actually random. Failing a statistical randomness test is not a good indicator of course!

Make a folder for testing, and get hold of [http://www.fourmilab.ch/random/ ENT]:

<pre>
mkdir /tmp/test/make
cd /tmp/test/make
wget http://www.fourmilab.ch/random/random.zip
unzip random.zip
make
mv ./ent /tmp/test/
cd /tmp/test
</pre>

Create some random data. In this example we read from /dev/urandom:

<pre>dd if=/dev/urandom of=/tmp/test/urandomfile bs=1 count=16384</pre>

Run the ENT test against it:

{{Cmd|./ent /tmp/test/urandomfile}}

Try the same test whilst treating the data as a stream of bits and printing an account of character occurrences:

{{Cmd|./ent -b -c /tmp/test/urandomfile}}

Note any differences against the previous test.

I propose also generating larger streams of data (10's or 100's of MB) and testing against this too. Any repeating data or patterns (caused by a small/poor seed value for instance) will make spotting any weaknesses and a lack of randomness much easier across large amounts of data than across small amounts.

I also suggest running the test against known non-random files, so you may see that some tests show that such a file can have some characteristics of a random file, whilst completely failing other randomness tests.

Finally, once you are done testing with ENT, it's good practice to delete the working folder:

{{Cmd|rm -r /tmp/test/}}

=== Other tests ===

Other tests include [http://www.stat.fsu.edu/pub/diehard/ diehard] and [http://www.phy.duke.edu/~rgb/General/dieharder.php dieharder]

== Further reading ==

[http://rsmith.home.xs4all.nl/howto/fun-with-encryption-and-randomness.html visualising randomness]

[http://www.linuxfromscratch.org/hints/downloads/files/entropy.txt linux from scratch]

[http://blog.cloudflare.com/ensuring-randomness-with-linuxs-random-number-generator Cloudflare]

[https://tools.ietf.org/html/rfc4086 RFC 4086 - Randomness Requirements for Security]

[https://calomel.org/entropy_random_number_generators.html calomel.org]

[http://www.av8n.com/turbid/paper/turbid.htm Turbid]

[http://blog.cryptographyengineering.com/2012/02/random-number-generation-illustrated.html Random number generation: An illustrated primer]

[https://factorable.net/weakkeys12.extended.pdf Mining Your Ps and Qs: Detection of Widespread Weak Keys in Network Devices, PDF]

[http://www.pinkas.net/PAPERS/gpr06.pdf Analysis of the Linux Random Number Generator, PDF]

[http://cryptome.org/2014/03/eat-entropy-have-it.pdf How to Eat Your Entropy and Have it Too — Optimal Recovery Strategies for Compromised RNGs, PDF]

[http://eprint.iacr.org/2013/338.pdf Security Analysis of Pseudo-Random Number Generators with Input: /dev/random is not Robust, PDF]

[[Category:Server]]

Alpine configuration management scripts

2014-06-09T15:07:36Z

Ginjachris: added busybox to setup-ntpd

This page summarizes the low-level behavior of the {{Path|/sbin/setup-*}} scripts on the Alpine ISO (and in a normal Alpine install).

== setup-alpine ==

For a higher-level walkthrough (using the "sys" installmode), see [[Install to disk|Basic HDD install]].

This script accepts the following command-line switches (you can run <code>setup-alpine -h</code> to see a usage message).

{{Define|-a|Create an overlay file: this creates a temporary directory and saves its location in ROOT; however, the script doesn't export this variable so I think this feature isn't currently functional.}}
;-c <var>answerfile</var>
:Create a new "answerfile", with default choices. You can edit the file and then invoke <code>setup-alpine -f <var>answerfile</var></code>.
;-f <var>answerfile</var>
:Use an existing "answerfile", which may override some or all of the interactive prompts.
{{Define|-q|Run in "quick mode." See below for details.}}

The script's behavior is to do the following, in order. Bracketed options represent extra configuration choices that can be supplied when running the auxiliary setup scripts manually, or by supplying an "answerfile".

# <code>setup-keymap</code> [us us]
# [[#setup-hostname|setup-hostname]] [-n alpine-test]
# [[#setup-interfaces|setup-interfaces]] [-i < interfaces-file]
# <code>/etc/init.d/networking --quiet start &</code>
# if none of the networking interfaces were configured using dhcp, then: [[#setup-dns|setup-dns]] [-d example.com -n "8.8.8.8 [...]"]
# set the root password
# if not in quick mode, then: [[#setup-timezone|setup-timezone]] [-z UTC | -z America/New_York | -p EST+5]
# enable the new hostname (<code>/etc/init.d/hostname --quiet restart</code>)
# add <code>networking</code> and <code>urandom</code> to the '''boot''' rc level, and <code>acpid</code> and <code>cron</code> to the '''default''' rc level, and start the '''boot''' and '''default''' rc services
# extract the fully-qualified domain name and hostname from {{Path|/etc/resolv.conf}} and <code>hostname</code>, and update {{Path|/etc/hosts}}
# [[#setup-proxy|setup-proxy]] [-q <nowiki>"http://webproxy:8080"</nowiki>], and activate proxy if it was configured
# <code>setup-apkrepos</code> [-r (to select a mirror randomly)]
# if not in quick mode, then: [[#setup-sshd|setup-sshd]] [-c openssh | dropbear | none]
# if not in quick mode, then: <code>setup-ntp</code> [-c chrony | openntpd | busybox | none]
# if not in quick mode, then: <code>DEFAULT_DISK=none</code> [[#setup-disk|setup-disk]] <code>-q</code> [-m data /dev/sda]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-lbu</code> [/media/sdb1]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-apkcache</code> [/media/sdb1/cache | none]

== setup-hostname ==

:<code>setup-hostname</code> [-h] [-n hostname]

Options:

'''-h''' <var>Show help</var>

'''-n''' <var>Specify hostname</var>

This script allows quick and easy setup of the system hostname by writing it to {{Path|/etc/hostname}}. The script prevents you from writing an invalid hostname (such as one that used invalid characters or starts with a '-' or is too long).
The script can be invoked manually or is called as part of the <code>setup-alpine</code> script.

== setup-interfaces ==
{{Cmd|setup-interfaces [-i < <var>interfaces-file</var>]}}

Note that the contents of <var>interfaces-file</var> has to be supplied as stdin, rather than naming the file as an additional argument. The contents should have the format of {{Path|/etc/network/interfaces}}, such as:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
hostname alpine-test

== setup-dns ==

:<code>setup-dns</code> [-h] [-d domain name] [-n name server]

Options:

'''-h''' <var>Show help</var>

'''-d''' <var>specify search domain name</var>

'''-n''' <var>name server IP</var>

The setup-dns script is stored in {{Path|/sbin/setup-dns}} and allows quick and simple setup of DNS servers (and a DNS search domain if required). Simply running <code>setup-dns</code> will allow interactive use of the script, or the options can be specified.

The information fed to this script is written to {{Path|/etc/resolv.conf}}

Example usage: {{Cmd|setup-dns -d example.org -n 8.8.8.8}}

Example {{Path|/etc/resolv.conf}}:

search example.org
nameserver 8.8.8.8

It can be run manually but is also invoked in the <code>setup-alpine</code> script unless interfaces are configured for DHCP.

== setup-timezone ==
:<code>setup-timezone</code> [-z UTC | -z America/New_York | -p EST+5]

Can pre-select the timezone using either of these switches:

'''-z''' <var>subfolder of</var> {{Path|/usr/share/zoneinfo}}

'''-p''' <var>POSIX TZ format</var>

== setup-proxy ==
:<code>setup-proxy</code> [-hq] [PROXYURL]

Options:

'''-h''' <var>Show help</var>

'''-q''' <var>Quiet mode</var> prevents changes from taking effect until after reboot

This script requests the system proxy to use in the form <code>http://<proxyurl>:<port></code> for example:
<code>http://10.0.0.1:8080</code>

To set no system proxy use <code>none</code>.
This script exports the following environmental variables:

<code>http_proxy=$proxyurl</code>

<code>https_proxy=$proxyurl</code>

<code>ftp_proxy=$proxyurl</code>

where <code>$proxyurl</code> is the value input.
If <code>none</code> was chosen then the value it is set to a blank value (and so no proxy is used).

== setup-sshd ==

:<code>setup-sshd</code> [-h] [-c choice of SSH daemon]

Options:

'''-h''' <var>Show help</var>

'''-c''' <var>SSH daemon</var> where SSH daemon can be one of the following:

<code>openssh</code> install the {{Pkg|openSSH}} daemon

<code>dropbear</code> install the {{Pkg|dropbear}} daemon

<code>none</code> Do not install an SSH daemon

Example usage: {{Cmd|setup-sshd -c dropbear}}

The setup-sshd script is stored in {{Path|/sbin/setup-sshd}} and allows quick and simple setup of either the OpenSSH or Dropbear SSH daemon & client.
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

== setup-disk ==

:<code>DEFAULT_DISK=none setup-disk -q</code> [-m data | sys] [<var>mountpoint directory</var> | /dev/sda ...]

This script accepts the following command-line switches:

;-k <var>kernel flavor</var>
;-o <var>apkovl file</var>
:Restore system from <var>apkovl file</var>
;-m data | sys
:Don't prompt for installation mode. With '''-m data''', the supplied devices are formatted to use as a {{Path|/var}} volume.
{{Define|-r|Use RAID1 with a single disk (degraded mode)}}
{{Define|-L|Create and use volumes in a LVM group}}
;-s <var>swap size in MB</var>
:Use 0 to disable swap
{{Define|-q|Exit quietly if no disks are found}}
{{Define|-v|Verbose mode}}

The script also honors the following environment variables:

<code>BOOT_SIZE</code>
:Size of the boot partition in MB; defaults to 100. Only used if '''-m sys''' is specified or interactively selected.

<code>SWAP_SIZE</code>
:Size of the swap volume in MB; set to 0 to disable swap. If not specified, will default to twice RAM, up to 4096, but won't be more than 1/3 the size of the smallest disk, and if less than 64 will just be 0. Only used if '''-m sys''' is specified or interactively selected.

<code>ROOTFS</code>
:Filesystem to use for the / volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs.

<code>BOOTFS</code>
:Filesystem to use for the /boot volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs.

<code>VARFS</code>
:Filesystem to use for the /var volume; defaults to ext4. Only used if '''-m data''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs.

<code>SYSROOT</code>
:Mountpoint to use when creating volumes and doing traditional disk install ('''-m data'''). Defaults to {{Path|/mnt}}.

<code>MBR</code>
:Path of MBR binary code, defaults to {{Path|/usr/share/syslinux/mbr.bin}}.



=== Partitioning ===

If you have complex partitioning needs, you can partition, format, and mount your volumes manually, then just supply the root mountpoint to <code>setup-disk</code>. Doing so implicitly behaves as though '''-m sys''' had also been specified.

See [[Setting up disks manually]] for more information.

==== RAID ====
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device. The array will always be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_1 RAID1] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-0.90_Superblock_Format --metadata=0.90]) for the /boot volumes, but will be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_5 RAID5] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-1_Superblock_Format --metadata=1.2] for non-boot volumes when 3 or more devices are supplied.

If you instead want to build your RAID array manually, see [[Setting up a software RAID1 array]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.

==== LVM ====
<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch. The group and volumes created by the script will have the following names:

* volume group: '''vg0'''
* swap volume: '''lv_swap''' (only created when swap size > 0)
* root volume: '''lv_root''' (only created when '''-m sys''' is specified or interactively selected)
* var volume: '''lv_var''' (only created when '''-m data''' is specified or interactively selected); also these volumes are currently always formatted as ext4.

The '''lv_var''' or '''lv_root''' volumes are created to occupy all remaining space in the volume group.

If you need to change any of these settings, you can use <code>vgrename</code>, <code>lvrename</code>, <code>lvreduce</code> or <code>lvresize</code>.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.



== setup-bootable ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Its purpose is to create media that boots into tmpfs by copying the contents of an ISO onto a USB key, CF, or similar media.

For a higher-level walkthrough, see [[Create a Bootable USB#Creating_a_bootable_Alpine_Linux_USB_Stick_from_the_command_line|Creating a bootable Alpine Linux USB Stick from the command line]].

This script accepts the following arguments and command-line switches (you can run <code>setup-bootable -h</code> to see a usage message).

{{Cmd|setup-bootable <var>source</var> [<var>dest</var>]}}

The argument <var>source</var> can be a directory or an ISO (will be mounted to <code>MNT</code> or {{Path|/mnt}}) or a URL (will be downloaded with <code>WGET</code> or <code>wget</code>). The argument <var>dest</var> can be a directory mountpoint, or will default to {{Path|/media/usb}} if not supplied.

{{Define|-k|Keep alpine_dev in {{Path|syslinux.cfg}}; otherwise, replace with UUID.}}
{{Define|-u|Upgrade mode: keep existing {{Path|syslinux.cfg}} and don't run <code>syslinux</code>}}
{{Define|-f|Overwrite {{Path|syslinux.cfg}} even if '''-u''' was specified.}}
{{Define|-s|Force the running of <code>syslinux</code> even if '''-u''' was specified.}}
{{Define|-v|Verbose mode}}

The script will ensure that <var>source</var> and <var>dest</var> are available; will copy the contents of <var>source</var> to <var>dest</var>, ensuring first that there's enough space; and unless '''-u''' was specified, will make <var>dest</var> bootable.



== setup-xorg-base ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Installs the following packages: <code>xorg-server xf86-video-vesa xf86-input-evdev xf86-input-mouse xf86-input-keyboard udev</code>.

Additional packages can be supplied as arguments to <code>setup-xorg-base</code>. You might need, for example, some of: <code>xf86-input-synaptics xf86-video-<var>something</var> xinit</code>.

== Documentation needed ==

=== setup-xen-dom0 ===

=== setup-gparted-desktop ===
Uses openbox.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

=== setup-mta ===
Uses ssmtp.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

=== setup-acf ===
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

This script was named <code>setup-webconf</code> before Alpine 1.9 beta 4.

See [[:Category:ACF|ACF pages]] for more information.

=== setup-ntp ===

[[Category:Installation]]

Alpine configuration management scripts

2014-06-09T15:05:15Z

Ginjachris: /* setup-sshd */

This page summarizes the low-level behavior of the {{Path|/sbin/setup-*}} scripts on the Alpine ISO (and in a normal Alpine install).

== setup-alpine ==

For a higher-level walkthrough (using the "sys" installmode), see [[Install to disk|Basic HDD install]].

This script accepts the following command-line switches (you can run <code>setup-alpine -h</code> to see a usage message).

{{Define|-a|Create an overlay file: this creates a temporary directory and saves its location in ROOT; however, the script doesn't export this variable so I think this feature isn't currently functional.}}
;-c <var>answerfile</var>
:Create a new "answerfile", with default choices. You can edit the file and then invoke <code>setup-alpine -f <var>answerfile</var></code>.
;-f <var>answerfile</var>
:Use an existing "answerfile", which may override some or all of the interactive prompts.
{{Define|-q|Run in "quick mode." See below for details.}}

The script's behavior is to do the following, in order. Bracketed options represent extra configuration choices that can be supplied when running the auxiliary setup scripts manually, or by supplying an "answerfile".

# <code>setup-keymap</code> [us us]
# [[#setup-hostname|setup-hostname]] [-n alpine-test]
# [[#setup-interfaces|setup-interfaces]] [-i < interfaces-file]
# <code>/etc/init.d/networking --quiet start &</code>
# if none of the networking interfaces were configured using dhcp, then: [[#setup-dns|setup-dns]] [-d example.com -n "8.8.8.8 [...]"]
# set the root password
# if not in quick mode, then: [[#setup-timezone|setup-timezone]] [-z UTC | -z America/New_York | -p EST+5]
# enable the new hostname (<code>/etc/init.d/hostname --quiet restart</code>)
# add <code>networking</code> and <code>urandom</code> to the '''boot''' rc level, and <code>acpid</code> and <code>cron</code> to the '''default''' rc level, and start the '''boot''' and '''default''' rc services
# extract the fully-qualified domain name and hostname from {{Path|/etc/resolv.conf}} and <code>hostname</code>, and update {{Path|/etc/hosts}}
# [[#setup-proxy|setup-proxy]] [-q <nowiki>"http://webproxy:8080"</nowiki>], and activate proxy if it was configured
# <code>setup-apkrepos</code> [-r (to select a mirror randomly)]
# if not in quick mode, then: [[#setup-sshd|setup-sshd]] [-c openssh | dropbear | none]
# if not in quick mode, then: <code>setup-ntp</code> [-c chrony | openntpd | none]
# if not in quick mode, then: <code>DEFAULT_DISK=none</code> [[#setup-disk|setup-disk]] <code>-q</code> [-m data /dev/sda]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-lbu</code> [/media/sdb1]
# if installation mode selected during setup-disk was "data" instead of "sys", then: <code>setup-apkcache</code> [/media/sdb1/cache | none]

== setup-hostname ==

:<code>setup-hostname</code> [-h] [-n hostname]

Options:

'''-h''' <var>Show help</var>

'''-n''' <var>Specify hostname</var>

This script allows quick and easy setup of the system hostname by writing it to {{Path|/etc/hostname}}. The script prevents you from writing an invalid hostname (such as one that used invalid characters or starts with a '-' or is too long).
The script can be invoked manually or is called as part of the <code>setup-alpine</code> script.

== setup-interfaces ==
{{Cmd|setup-interfaces [-i < <var>interfaces-file</var>]}}

Note that the contents of <var>interfaces-file</var> has to be supplied as stdin, rather than naming the file as an additional argument. The contents should have the format of {{Path|/etc/network/interfaces}}, such as:

auto lo
iface lo inet loopback

auto eth0
iface eth0 inet dhcp
hostname alpine-test

== setup-dns ==

:<code>setup-dns</code> [-h] [-d domain name] [-n name server]

Options:

'''-h''' <var>Show help</var>

'''-d''' <var>specify search domain name</var>

'''-n''' <var>name server IP</var>

The setup-dns script is stored in {{Path|/sbin/setup-dns}} and allows quick and simple setup of DNS servers (and a DNS search domain if required). Simply running <code>setup-dns</code> will allow interactive use of the script, or the options can be specified.

The information fed to this script is written to {{Path|/etc/resolv.conf}}

Example usage: {{Cmd|setup-dns -d example.org -n 8.8.8.8}}

Example {{Path|/etc/resolv.conf}}:

search example.org
nameserver 8.8.8.8

It can be run manually but is also invoked in the <code>setup-alpine</code> script unless interfaces are configured for DHCP.

== setup-timezone ==
:<code>setup-timezone</code> [-z UTC | -z America/New_York | -p EST+5]

Can pre-select the timezone using either of these switches:

'''-z''' <var>subfolder of</var> {{Path|/usr/share/zoneinfo}}

'''-p''' <var>POSIX TZ format</var>

== setup-proxy ==
:<code>setup-proxy</code> [-hq] [PROXYURL]

Options:

'''-h''' <var>Show help</var>

'''-q''' <var>Quiet mode</var> prevents changes from taking effect until after reboot

This script requests the system proxy to use in the form <code>http://<proxyurl>:<port></code> for example:
<code>http://10.0.0.1:8080</code>

To set no system proxy use <code>none</code>.
This script exports the following environmental variables:

<code>http_proxy=$proxyurl</code>

<code>https_proxy=$proxyurl</code>

<code>ftp_proxy=$proxyurl</code>

where <code>$proxyurl</code> is the value input.
If <code>none</code> was chosen then the value it is set to a blank value (and so no proxy is used).

== setup-sshd ==

:<code>setup-sshd</code> [-h] [-c choice of SSH daemon]

Options:

'''-h''' <var>Show help</var>

'''-c''' <var>SSH daemon</var> where SSH daemon can be one of the following:

<code>openssh</code> install the {{Pkg|openSSH}} daemon

<code>dropbear</code> install the {{Pkg|dropbear}} daemon

<code>none</code> Do not install an SSH daemon

Example usage: {{Cmd|setup-sshd -c dropbear}}

The setup-sshd script is stored in {{Path|/sbin/setup-sshd}} and allows quick and simple setup of either the OpenSSH or Dropbear SSH daemon & client.
It can be run manually but is also invoked in the <code>setup-alpine</code> script.

== setup-disk ==

:<code>DEFAULT_DISK=none setup-disk -q</code> [-m data | sys] [<var>mountpoint directory</var> | /dev/sda ...]

This script accepts the following command-line switches:

;-k <var>kernel flavor</var>
;-o <var>apkovl file</var>
:Restore system from <var>apkovl file</var>
;-m data | sys
:Don't prompt for installation mode. With '''-m data''', the supplied devices are formatted to use as a {{Path|/var}} volume.
{{Define|-r|Use RAID1 with a single disk (degraded mode)}}
{{Define|-L|Create and use volumes in a LVM group}}
;-s <var>swap size in MB</var>
:Use 0 to disable swap
{{Define|-q|Exit quietly if no disks are found}}
{{Define|-v|Verbose mode}}

The script also honors the following environment variables:

<code>BOOT_SIZE</code>
:Size of the boot partition in MB; defaults to 100. Only used if '''-m sys''' is specified or interactively selected.

<code>SWAP_SIZE</code>
:Size of the swap volume in MB; set to 0 to disable swap. If not specified, will default to twice RAM, up to 4096, but won't be more than 1/3 the size of the smallest disk, and if less than 64 will just be 0. Only used if '''-m sys''' is specified or interactively selected.

<code>ROOTFS</code>
:Filesystem to use for the / volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs.

<code>BOOTFS</code>
:Filesystem to use for the /boot volume; defaults to ext4. Only used if '''-m sys''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs.

<code>VARFS</code>
:Filesystem to use for the /var volume; defaults to ext4. Only used if '''-m data''' is specified or interactively selected. Supported filesystems are: ext2 ext3 ext4 btrfs.

<code>SYSROOT</code>
:Mountpoint to use when creating volumes and doing traditional disk install ('''-m data'''). Defaults to {{Path|/mnt}}.

<code>MBR</code>
:Path of MBR binary code, defaults to {{Path|/usr/share/syslinux/mbr.bin}}.



=== Partitioning ===

If you have complex partitioning needs, you can partition, format, and mount your volumes manually, then just supply the root mountpoint to <code>setup-disk</code>. Doing so implicitly behaves as though '''-m sys''' had also been specified.

See [[Setting up disks manually]] for more information.

==== RAID ====
<code>setup-disk</code> will automatically build a RAID array if you supply the '''-r''' switch, or if you specify more than one device. The array will always be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_1 RAID1] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-0.90_Superblock_Format --metadata=0.90]) for the /boot volumes, but will be [https://en.m.wikipedia.org/wiki/Standard_RAID_levels#RAID_5 RAID5] (and [https://raid.wiki.kernel.org/index.php/RAID_superblock_formats#The_version-1_Superblock_Format --metadata=1.2] for non-boot volumes when 3 or more devices are supplied.

If you instead want to build your RAID array manually, see [[Setting up a software RAID1 array]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.

==== LVM ====
<code>setup-disk</code> will automatically build and use volumes in a LVM group if you supply the '''-L''' switch. The group and volumes created by the script will have the following names:

* volume group: '''vg0'''
* swap volume: '''lv_swap''' (only created when swap size > 0)
* root volume: '''lv_root''' (only created when '''-m sys''' is specified or interactively selected)
* var volume: '''lv_var''' (only created when '''-m data''' is specified or interactively selected); also these volumes are currently always formatted as ext4.

The '''lv_var''' or '''lv_root''' volumes are created to occupy all remaining space in the volume group.

If you need to change any of these settings, you can use <code>vgrename</code>, <code>lvrename</code>, <code>lvreduce</code> or <code>lvresize</code>.

If you instead want to build your LVM system manually, see [[Setting up Logical Volumes with LVM]]. Then format and mount the disks, and supply the root mountpoint to <code>setup-disk</code>.



== setup-bootable ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Its purpose is to create media that boots into tmpfs by copying the contents of an ISO onto a USB key, CF, or similar media.

For a higher-level walkthrough, see [[Create a Bootable USB#Creating_a_bootable_Alpine_Linux_USB_Stick_from_the_command_line|Creating a bootable Alpine Linux USB Stick from the command line]].

This script accepts the following arguments and command-line switches (you can run <code>setup-bootable -h</code> to see a usage message).

{{Cmd|setup-bootable <var>source</var> [<var>dest</var>]}}

The argument <var>source</var> can be a directory or an ISO (will be mounted to <code>MNT</code> or {{Path|/mnt}}) or a URL (will be downloaded with <code>WGET</code> or <code>wget</code>). The argument <var>dest</var> can be a directory mountpoint, or will default to {{Path|/media/usb}} if not supplied.

{{Define|-k|Keep alpine_dev in {{Path|syslinux.cfg}}; otherwise, replace with UUID.}}
{{Define|-u|Upgrade mode: keep existing {{Path|syslinux.cfg}} and don't run <code>syslinux</code>}}
{{Define|-f|Overwrite {{Path|syslinux.cfg}} even if '''-u''' was specified.}}
{{Define|-s|Force the running of <code>syslinux</code> even if '''-u''' was specified.}}
{{Define|-v|Verbose mode}}

The script will ensure that <var>source</var> and <var>dest</var> are available; will copy the contents of <var>source</var> to <var>dest</var>, ensuring first that there's enough space; and unless '''-u''' was specified, will make <var>dest</var> bootable.



== setup-xorg-base ==
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

Installs the following packages: <code>xorg-server xf86-video-vesa xf86-input-evdev xf86-input-mouse xf86-input-keyboard udev</code>.

Additional packages can be supplied as arguments to <code>setup-xorg-base</code>. You might need, for example, some of: <code>xf86-input-synaptics xf86-video-<var>something</var> xinit</code>.

== Documentation needed ==

=== setup-xen-dom0 ===

=== setup-gparted-desktop ===
Uses openbox.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

=== setup-mta ===
Uses ssmtp.

This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

=== setup-acf ===
This is a standalone script; it's not invoked by <code>setup-alpine</code> but must be run manually.

This script was named <code>setup-webconf</code> before Alpine 1.9 beta 4.

See [[:Category:ACF|ACF pages]] for more information.

=== setup-ntp ===

[[Category:Installation]]

Setting up Explicit Squid Proxy

2014-06-05T19:33:33Z

Ginjachris: Tidying of /* Blocking domains */

[http://www.squid-cache.org/ Squid] is a caching proxy for the Web supporting HTTP, HTTPS, FTP, and more. It reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It is licensed under the [https://gnu.org/licenses/gpl.html GNU GPL].

If you are looking to setup a transparent squid proxy, see [[Setting up Transparent Squid Proxy|this page]]

== Terminology ==

=== client ===
A client is often considered a user of a PC or similar system, but more accurately a client is the applications a person uses to access web pages and other resources, and the OS they are running on.

=== proxy ===
A [https://en.wikipedia.org/wiki/Proxy_server proxy] is a device which makes connections on behalf of clients. If we consider a common [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection, there is one [http://en.wikipedia.org/wiki/Transmission_Control_Protocol TCP] connection between the client (source) and the proxy, and a separate TCP connection between the proxy and the server (destination). Consider this beautiful diagram:
<pre>
Client<---------->|PROXY|<------------>Server
A B
</pre>
Point '''A''' is the '''client-side connection''' and point '''B''' is the '''server-side connection'''.

These are separate, distinct connections, so for example the client-side could be encrypted and the server-side in plaintext (unencrypted), or the client-side could use browser user-agent header ''x'' and the server-side connection could use browser user-agent header ''y''.

The proxy is effectively acting as a server to the client, and as a client to the server (OCS). Without a proxy, the connection would simply be from client to server. The destination server is often referred to as the 'OCS' or 'Origin Content Server' - this simply means the server hosting the objects that the client requests (for example the web pages that you want).

The above is of course a simplified version of things. Other factors, such as the HTTP version of the client browser, or existence of the object in cache on the proxy, will have impacts on how many server-side connections are created.

==== explicit forward proxy ====
An explicit proxy is one in which the client is ''explicitly configured'' to use the proxy, and as such are aware of the existence of the proxy on the network. When the client sends packets to an explicit proxy, they are addressed to the proxy server listening address and port.
Squid usually listens for explicit traffic on TCP port 3128 but TCP port 8080 is a common explicit proxy listening port. AFAIK all explicit proxy deployments are forward proxy deployments, where the clients can make use of the caching and optimisation features of the proxy when making outbound requests. An explicit proxy can be involved in authentication of the client.
''This article discusses this type of proxy deployment.''

==== [[Setting up Transparent Squid Proxy|transparent]] forward proxy ====
A transparent proxy, also known as an intercepting proxy, does not require any configuration changes on the client, since traffic is ''transparently'' sent to the proxy, usually through traffic redirection by a router. When the client sends packets, they are addressed to the destination server. A transparent server cannot be involved with client authentication; a client cannot authenticate to a proxy server that it is not (or should not) be aware of.

==== reverse proxy ====
A [https://en.wikipedia.org/wiki/Reverse_proxy reverse proxy] sits in front of a resource such as a web server and answers queries from clients, caching content from the server and optimising connections to it.

=== cache ===
A cache is simply an object store. A proxy will usually cache objects (images, html text, downloaded files etc) that are requested by clients, which means storing the objects on the proxy either in RAM or on disk.
This has the benefit of a client being able to get the object from the proxy, without having to wait for the proxy to connect out to the destination server (OCS) and download the object again, resulting in a better client experience ("the web pages seem to load faster") and reduced bandwidth (less connections made server side, especially if we consider objects that are repeatedly requested).

Caching is influenced by proxy configuration (what to cache) and by numerous [https://en.wikipedia.org/wiki/HTTP_header HTTP headers] (am I allowed to cache this object? How long should I cache it for?) such as 'Expires', 'Cache Control', 'If-Modified-Since' and 'Last-Modified'.
A proxy will usually keep its cache fresh by making requests for cached objects independent of client requests for the objects.

=== More information ===
You may also wish to review https://devcentral.f5.com/articles/the-concise-guide-to-proxies which provides further information on various proxy types.

== Installation ==
Install the {{Pkg|squid}} package:
{{Cmd|apk add squid}}

If you wish to use the Alpine Configuration Framework (ACF) front-end for squid, install the {{Pkg|acf-squid}} package:
{{Cmd|apk add acf-squid}}
You can then logon to the device over https://x.x.x.x (replace x.x.x.x with the IP of your server of course) and manage the squid configuration files and stop/start/restart the daemon etc.

== Basic configuration ==
=== Config file ===
The main configuration file is <code>/etc/squid/squid.conf</code>. Lines beginning with a '#' are comments.
squid should already come with a basic working configuration file but an example configuration file is shown below, which will get you up and running quickly and is well commented but please change the localnet definition for a more restrictive one:

<pre>
## Tested and working on squid 3.3.10-r0 and Alpine 2.7.1 (kernel 3.10.19-0-grsec), 64-bit
## Example rule allowing access from your local networks.
## Adapt to list your (internal) IP networks from where browsing
## should be allowed
acl localnet src 10.0.0.0/8 # RFC1918 possible internal network
acl localnet src 172.16.0.0/12 # RFC1918 possible internal network
acl localnet src 192.168.0.0/16 # RFC1918 possible internal network
## Allow anyone to use the proxy (you should lock this down to client networks only!):
# acl localnet src all
## IPv6 local addresses:
acl localnet src fc00::/7 # RFC 4193 local private network range
acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80 # http
acl Safe_ports port 21 # ftp
acl Safe_ports port 443 # https
acl Safe_ports port 70 # gopher
acl Safe_ports port 210 # waiss
acl Safe_ports port 1025-65535 # unregistered ports
acl Safe_ports port 280 # http-mgmt
acl Safe_ports port 488 # gss-http
acl Safe_ports port 591 # filemaker
acl Safe_ports port 777 # multiling http
acl CONNECT method CONNECT
acl QUERY urlpath_regex cgi-bin \? asp aspx jsp

## Prevent caching jsp, cgi-bin etc
cache deny QUERY

## Only allow access to the defined safe ports whitelist
http_access deny !Safe_ports

## Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

## Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

## We strongly recommend the following be uncommented to protect innocent
## web applications running on the proxy server who think the only
## one who can access services on "localhost" is a local user
http_access deny to_localhost

##
## INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
##

## Example rule allowing access from your local networks.
## Adapt localnet in the ACL section to list your (internal) IP networks
## from where browsing should be allowed
http_access allow localnet
http_access allow localhost

## And finally deny all other access to this proxy
http_access deny all

## Squid normally listens to port 3128
http_port 3128
## If you have multiple interfaces you can specify to listen on one IP like this:
#http_port 1.2.3.4:3128

## Uncomment and adjust the following to add a disk cache directory.
## 1024 is the disk space to use for cache in MB, adjust as you see fit!
## Default is no disk cache
#cache_dir ufs /var/cache/squid 1024 16 256
## Better, use 'aufs' cache type, see
##http://www.squid-cache.org/Doc/config/cache_dir/ for info.
#cache_dir aufs /var/cache/squid 1024 16 256
## Recommended to only change cache type when squid is stopped, and use 'squid -z' to
## ensure cache is (re)created correctly

## Leave coredumps in the first cache dir
#coredump_dir /var/cache/squid

## Where does Squid log to?
#access_log /var/log/squid/access.log
## Use the below to turn off access logging
access_log none
## When logging, web auditors want to see the full uri, even with the query terms
#strip_query_terms off
## Keep 7 days of logs
#logfile_rotate 7

## How much RAM, in MB, to use for cache? Default since squid 3.1 is 256 MB
cache_mem 64 MB

## Maximum size of individual objects to store in cache
maximum_object_size 1 MB

## Amount of data to buffer from server to client
read_ahead_gap 64 KB

## Use X-Forwarded-For header?
## Some consider this a privacy/security risk so it is often disabled
## However it can be useful to identify misbehaving/problematic clients
#forwarded_for on
forwarded_for delete

## Suppress sending squid version information
httpd_suppress_version_string on

## How long to wait when shutting down squid
shutdown_lifetime 30 seconds

## Replace the User Agent header. Be sure to deny the header first, then replace it :)
#request_header_access User-Agent deny all
#request_header_replace User-Agent Mozilla/5.0 (Windows; MSIE 9.0; Windows NT 9.0; en-US)

## What hostname to display? (defaults to system hostname)
#visible_hostname a_proxy

## Use a different hosts file?
#hosts_file /path/to/file

## Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp: 1440 20% 10080
refresh_pattern ^gopher: 1440 0% 1440
refresh_pattern -i (/cgi-bin/|\?) 0 0% 0
refresh_pattern . 0 20% 4320
</pre>

'''Note:'''If you change the squid configuration file, you do not need to restart squid in order to load the changes, just use this command instead:
{{Cmd|squid -k reconfigure}}

=== Testing ===

==== Start and check squid ====
Start the squid service:
{{Cmd|rc-service squid start}}

To start squid automatically at boot:
{{Cmd|rc-update add squid}}

Check the squid configuration for errors:
{{Cmd|squid -k check}}

If there is no feedback, everything is gravy! (that's a good thing).

Check that squid is listening for traffic, using netstat for example:

{{Cmd|netstat -tl}}
You should see a line showing a Local Address and the listening port (in our example config above it is set to 3128). If you don't see this, check the "http_port" directive is set in the config file and has a value. Ensure this port isn't being used by something else on the system.

Remember to ensure the squid proxy has valid [[Configure Networking|IP configuration]] including default gateway etc.

==== Configure the client ====
Each application using the proxy will have to be configured to send traffic via the proxy. If we assume that our squid proxy is running on IP address 10.0.0.1, port 3128, we would configure the Firefox browser in the following manner:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Manual proxy configuration''' and tick the 'use this proxy server for all protocols' box
* Under '''HTTP Proxy:''' add the squid listening IP address, 10.0.0.1. In the '''Port:''' section add the squid listening port 3128
* Click '''OK''' to save the changes.

Now browse, you should have internet access, via the proxy!

Many Operating Systems allow a system proxy to be set. Firefox can be set to use the system proxy settings:
* '''Tools>Options>Advanced>Network>Settings...'''
* Select '''Use system proxy settings'''
* Click '''OK''' to save the changes.

The [https://wiki.archlinux.org/index.php/Proxy_settings system proxy settings] themselves vary from system to system but on an Alpine install you can simply run the [[Alpine Setup Scripts#setup-proxy|setup-proxy]] script.

It is also possible to configure the browser to use a [https://en.wikipedia.org/wiki/Proxy_auto-config PAC file]. This file is usually hosted on a webserver (which may also be the proxy, but doesn't have to be) and it tells the browser what requests to send to the proxy and which ones to send direct (bypassing the proxy).

The [http://wiki.squid-cache.org/SquidFaq/ConfiguringBrowsers Squid FAQ on configuring browsers] offers more information on this topic.

==== Logs ====

If you've set the proxy to take access logs, you can view these to see client requests coming in:
{{Cmd|tail -f /var/log/squid/access.log}}
Use Ctrl-C to exit back to the prompt.

== SSL interception or SSL bumping ==
The offical squid documentation apears to prefer the term ''SSL interception'' for [[Setting up Transparent Squid Proxy|transparent]] squid deployments and ''SSL bumping'' for explicit proxy deployments. Nonetheless, both environments use the [http://www.squid-cache.org/Doc/config/ssl_bump/ ssl_bump configuration directive] (and some others) in <code>/etc/squid/squid.conf</code> for their configuration.
In general terminology, ''SSL interception'' is generally used to describe both deployments and that will be the term used here. We are, of course, dealing with an ''explicit forward proxy'' configuration here.

==== Behaviour without SSL interception ====
Clients behind an explicit proxy use the [http://tools.ietf.org/rfc/rfc2817 'CONNECT'] HTTP method. The first connection to the proxy port uses HTTP and specifies the destination server (often termed the Origin Content Server, or OCS). After this the proxy simply acts as a [http://tools.ietf.org/id/draft-luotonen-web-proxy-tunneling-01.txt tunnel], and blindly proxies the connection without inspecting the traffic.

==== Behaviour with SSL interception ====
Using this method, clients still use the [http://tools.ietf.org/rfc/rfc2817 CONNECT] method but the client uses the certificate from the proxy (so it must be a certificate trusted by the client) to encrypt the traffic. Thus, the proxy is able to decrypt and view the traffic on the client-side before creating another encrypted connection server-side. This enables the proxy to, in essence, launch a man-in-the-middle 'attack' but also allows it to do all the things is can with plain, unencrypted HTTP traffic, like change the browser [https://en.wikipedia.org/wiki/User_agent User-Agent] reported to the server.

==== Configuration ====
===== Add packages =====
Add the {{Pkg|ca-certificates}} package (required to trust common Certificate Authority (CA) certificates) and the {{Pkg|openssl}} package (to create self-signed certificate or CSR). The <code>-U</code> option ensures we update the package list first:
{{Cmd|apk -U add ca-certificates openssl}}

===== Generate cert/key pair =====
You obviously don't need to follow ''both'' of the next sections. Either generate a self-signed certificate or a CA signed one (you have to pay for the latter) and then amend the squid configuration to enable SSL interception and point it to the key/cert pair generated in these steps.

====== Generate a self-signed certificate with OpenSSL ======
The following example command will produce a working cert/key pair, saved to {{Path|/etc/squid/squid.pem}}:
{{Cmd|openssl req -newkey rsa:4096 -x509 -keyout /etc/squid/squid.pem -out /etc/squid/squid.pem -days 365 -nodes}}
Then adjust permissions:
{{Cmd|chmod 400 /etc/squid/squid.pem}}
In the above example we save the cetificate and key to the same file; they can be saved to separate files if you wish, just adjust paths accordingly.
====== Generate a CSR to get a CA-signed certificate ======

Create a private key using the syntax <code>openssl genrsa -out <key_path_and_name> <keysize></code>

For example: {{Cmd|openssl genrsa -out /etc/squid/squid.key 2048}}

Create the CSR with the syntax <code>openssl req -new -key <key_path_and_name> -out <csr_path_and_name></code>

For example:

{{Cmd|openssl req -new -key /etc/squid/squid.key -out /etc/squid/squid.csr}}

You then need to supply the CSR (Certificate Signing Request) to your Certificate Authority (CA). '''Do not send them, or anyone else, your private key. It should remain private!'''

Some CA's (such as [http://www.thawte.nl/en/support/test+your+csr/ Thawte] and [https://ssl-tools.verisign.com/checker/ Verisign]) provide an online CSR checker, so you can ensure the CSR is valid before providing it to them.

Once the CA receive the CSR and do their thing they should send you back the CA signed public key. Request it in .pem format if possible (it's a widely used standard for certs). You then need to copy this back onto the Squid proxy, to {{Path|/etc/squid/}} if you are following the example here.

Remember to [[Setting up Explicit Squid Proxy#Amend_.2Fetc.2Fsquid.2Fsquid.conf|amend the squid configuration]] to point at the correct locations of the private key and CA signed certificate.

===== Amend /etc/squid/squid.conf =====
Next, we need to amend the squid configuration file to use SSL interception. In the below example, we will add a few lines, then amend the <code>http_port</code> directive so that it still serves HTTP requests, but also performs SSL interception on HTTPS connections that are established via the HTTP method CONNECT. You can use a separate <code>http_port</code> for each if you wish, but remember to amend the client configuration to send HTTPS traffic to the alternative port.

<pre>
## Use the below to avoid proxy-chaining
always_direct allow all
## Always complete the server-side handshake before client-side (recommended)
ssl_bump server-first all
## Allow server side certificate errors such as untrusted certificates, otherwise the connection is closed for such errors
sslproxy_cert_error allow all
## Or maybe deny all server side certificate errors according to your company policy
#sslproxy_cert_error deny all
## Accept certificates that fail verification (should only be needed if using 'sslproxy_cert_error allow all')
sslproxy_flags DONT_VERIFY_PEER

## Modify the http_port directive to perform SSL interception
## Ensure to point to the cert/key created earlier
## Disable SSLv2 because it isn't safe
http_port 3128 ssl-bump cert=/etc/squid/squid.pem key=/etc/squid/squid.pem generate-host-certificates=on options=NO_SSLv2
</pre>

===== Fix client SSL Warnings =====

You will need to install the self-signed proxy certificate (in our example we saved it to /etc/squid/squid.pem) to all clients, otherwise they will probably get an SSL error for every domain they visit over HTTPS. It is important to install the certificate as a '''Certificate Authority''' (CA) certificate to the client browser for trust to establish properly. If you are using a CA signed certificate (not a self-signed one) then the browser probably already trusts the certificate and so this step will likely not be needed.

For Internet Explorer, you can likely double-click the .pem certificate and use the Certificate Import Wizard to manually install the certificate to the '''Trusted Root Certification Authorities''' certificate store.

For Firefox, use '''Tools>Options>Advanced>Certificates>View Certificates.''' Under the '''Authorities''' tab, use '''Import...''' to add the certificate as a trusted authority. Installing the certificate as any other kind of certificate will result in a poor user experience.

'''Note:'''If you see the error ''This certificate is already installed as a certificate authority.'' be sure to check all locations for existence of the certificate and remove (delete) it wherever found. Firefox likes to install certificates as '''Server''' certificates rather than under '''Authorities''' as we would like. Once removing all traces of the certificate, please be sure to restart Firefox and try importing the certificate again.

===== Disable SSL interception for certain sites =====

There may be situations where you wish to disable SSL interception/SSL bumping for certain destinations due to issues with functionality or privacy concerns. As an example, a Windows Dropbox client refused to establish a secure connection because it did not trust the self-signed certificate in use by the proxy. Or, you may wish to allow user privacy to be retained when they are using hotmail.com.
In this example we will create an Access Control list (ACL) to prevent SSL interception to *.hotmail.com and *.dropbox.com. Remember that rule order is important, the first match wins! So put more specific rules at the top, more general rules below.

<pre>
## Disable ssl interception for dropbox.com and hotmail.com (and localhost)
acl no_ssl_interception dstdomain .dropbox.com .hotmail.com
ssl_bump none localhost
ssl_bump none no_ssl_interception
## Add the rest of your ssl-bump rules below
## e.g ssl_bump server-first all
## etc
</pre>

==== Further reading ====

[http://wiki.squid-cache.org/Features/HTTPS Squid HTTPS feature]

[http://wiki.squid-cache.org/Features/SslBump Squid SSL bump feature]

[http://wiki.squid-cache.org/Features/BumpSslServerFirst Squid bump-server-first feature]

[http://wiki.squid-cache.org/Features/MimicSslServerCert Squid SSL cert mimic feature]

[http://wiki.squid-cache.org/Features/DynamicSslCert Squid dynamic certificate generation page]

== Advert blocking ==
There are several methods to achieve this, you could simply create an ACL for known advert domains (see [[#Blocking_domains|blocking domains]] for an indication of how to do this).
Another options is to use a [https://en.wikipedia.org/wiki/Hosts_%28file%29 hosts file] specific to squid (i.e. unrelated to the system hosts file), which will direct traffic for known adverts/malware sites to the localhost. The connection can then either fail (because there is no web server running at 127.0.0.1:80 to service the requests that are redirected by the hosts file to localhost) and squid will display a standard error, or you can have a web server running that will respond with some form of 'advert blocked' page.

Blocking ads will save bandwidth and should improve page load times. As a drawback, some pages may look untidy or odd without advertising in place.

The first thing to do is either create a hosts file yourself or find a pre-configured one such as [http://winhelp2002.mvps.org/hosts.txt this one] (note that this file is free to use for personal use only, see the full license [http://creativecommons.org/licenses/by-nc-sa/3.0/ here].

Whichever method you choose, save the hosts file to the local filesystem, in our example to <code>/etc/squid/hosts.txt</code>

Then, add the <code>hosts_file</code> directive to the squid configuration:
<pre>
hosts_file /etc/squid/hosts.txt
</pre>

Remember to reload the configuration/restart the squid service for the changes to take effect.

== Blocking domains ==

If you have a large number of domains you wish to block, instead of adding them directly to the squid configuration file the best option is to create a separate list and reference this in the configuration file.
The domain list should have domains listed one per line. There is an example list (warning, this doesn't get updated!) available [https://dl.dropboxusercontent.com/u/30359454/Squid/porndomains.acl here] or [http://www.ginjachris.co.uk/porndomains.acl here]
We will refer to this list in our example below.

- Create your own, or download a domain list and save it to {{Path|/etc/squid/porndomains.acl}}:

<code>
<nowiki>
wget http://www.ginjachris.co.uk/porndomains.acl -O /etc/squid/porndomains.acl
</nowiki>
</code>

- Amend the squid configuration file at {{Path|/etc/squid/squid.conf}} as follows:
<code>
# block porn domains based on a URL filtering list
acl blacklistpr0n dstdomain "/etc/squid/porndomains.acl"
http_access deny blacklistpr0n
</code>

- Check the squid configuration for errors:

<code>
squid -k check
</code>

and if there are none, apply the changes:

<code>
squid -k reconfigure
</code>

- Done! Domains from the list should now be blocked.

You can of course create your own lists of domains and add blacklists/whitelists to your configuration based on the above example. Each list should of course have a unique name.

== DNS configuration ==
No additional DNS configuration is required since by default Squid will use the settings in /etc/resolv.conf.
You may wish to change this behaviour for your environment or tweak settings to improve performance, as per the below example. It's heavily commented as always for my examples, change to suit your needs.

<pre>
## Use DNS defined servers. Default is to use servers defined in /etc/resolv.conf
#dns_nameservers 10.0.0.1 192.168.0.1
## Should squid handle single-component names? Default is disabled
#dns_defnames enabled
## How many DNS child processes to spawn? Values shown are defaults
#dns_children 32 startup=1 idle=1
## Enable EDNS. Default is no ("none"). Size is specified in bytes.
#dns_packet_max none
## How often to retransmit DNS query? Default is 5 seconds, doubled every time all DNS servers have been tried.
#dns_retransmit_interval 5
## DNS query timeout. If no response is received to a DNS query within this time,
## all DNS servers for the queried domain are assumed to be unavailable.
## Default is 30 seconds
#dns_timeout 30 seconds
## Default is to use IPv6 to connect to sites where available, over IPv4.
## Turning this feature on reverses this and prefers IPv4 connections over IPv6
#dns_v4_first on
</pre>

== More information ==

[http://www.squid-cache.org/Doc/config/ Squid configuration directives]

[http://linux.die.net/man/8/squid Squid man page]

[https://wiki.archlinux.org/index.php/Squid Squid Arch linux wiki page]

[[Category:Server]]

User:Ginjachris

2014-05-29T13:41:52Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some awesome acoustic punk tunes I've discovered recently:

[http://grooveshark.com/s/My+Idea+Of+Fun/2LX80k?src=5 'My idea of fun' by Wingnut Dishwashers Union]

[http://grooveshark.com/s/Gimme+Coffee+Or+Death/3VTYAr?src=5 'Gimme coffee or death' by Mischief Brew]

[http://grooveshark.com/s/Picking+Sides/2LX6ZZ?src=5 'Picking sides' by Wingnut Dishwashers Union]

[http://grooveshark.com/s/DIY+Orgasms/17PM7B?src=5 'DIY orgasms' by Jonny Hobo and the Freight Trains]

[http://grooveshark.com/s/For+An+Old+Kentucky+Anarchist/46iV2L?src=5 'For an old Kentucky Anarchist' by The Orphans]

[http://grooveshark.com/s/Tone+Deaf/4Pmbc0?src=5 'Tone Deaf' by No Cops for Miles]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server
* Ash: modifying prompt etc, using ~/.profile
Courtesy of BitL0G1c:
# Automatically do an ls after each cd
c() {
if [ -n "$1" ]; then
cd "$@" && ls
else
cd ~ && ls
fi
}

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

User:Ginjachris

2014-05-29T13:37:07Z

Ginjachris:

Hello, my name is Chris and I'm a security analyst from the UK. I'm no coder so I'm currently contributing to the wiki and suggesting improvements.

Here's some awesome acoustic punk tunes I've discovered recently:

[http://grooveshark.com/s/My+Idea+Of+Fun/2LX80k?src=5 'My idea of fun' by Wingnut Dishwashers Union]

[http://grooveshark.com/s/Gimme+Coffee+Or+Death/3VTYAr?src=5 'Gimme coffee or death' by Mischief Brew]

[http://grooveshark.com/s/Picking+Sides/2LX6ZZ?src=5 'Picking sides' by Wingnut Dishwashers Union]

[http://grooveshark.com/s/DIY+Orgasms/17PM7B?src=5 'DIY orgasms' by Jonny Hobo and the Freight Trains]

[http://grooveshark.com/s/For+An+Old+Kentucky+Anarchist/46iV2L?src=5 'For an old Kentucky Anarchist' by The Orphans]

[http://grooveshark.com/s/Tone+Deaf/4Pmbc0?src=5 'Tone Deaf' by No Cops for Miles]

Pages I need to write:

* Time: the importance of time, plus Chrony & NTPD, how to run them as a client only and how to run them as a time server
* Ash: modifying prompt etc, using ~/.profile

Need a wiki article? Add it to the discussion page and I'll see what I can do :¬)

Lighttpd Advanced security

2014-05-11T20:46:38Z

Ginjachris: /* Perfect Forward Secrecy (PFS) */

For higher security [[Lighttpd]] can be configured to allow https access.

==Generate Certificate and Keys==
Either generate the public key and certificate and private key using {{Pkg|openssl}}, or by using the ones generated by installing [[Alpine_Configuration_Framework_Design| ACF]]. You don't need to do both, just do one or the other. The former method, with OpenSSL, is preferred since it gives greater control.

===Generate self-signed certificates with openssl ===
To generate certificates, openssl is needed.

{{Cmd|apk add openssl}}

Change to the lighttpd configuration directory

{{Cmd|cd /etc/lighttpd}}

With the command below the self-signed certificate and key pair are generated. A 2048 bit key is the minimum recommended at the time of writing, so we use '-newkey rsa:2048' in the command. Change to suit your needs. Answer all questions.

{{Cmd|openssl req -newkey rsa:2048 -x509 -keyout server.pem -out server.pem -days 365 -nodes}}

Adjust the permissions

{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

=== Generate self-signed certificates with acf ===

Install the [[Alpine_Configuration_Framework_Design| ACF]]

{{Cmd|setup-acf}}

Copy the generated certificate to the lighttpd configuration directory.

{{Cmd|mv /etc/ssl/mini_httpd/server.pem /etc/lighttpd/server.pem}}

Adjust the permissions

{{Cmd|chown root:root /etc/lighttpd/server.pem}}
{{Cmd|chmod 400 /etc/lighttpd/server.pem}}

mini_http is no longer needed.

{{Cmd|/etc/init.d/mini_httpd stop && rc-update del mini_httpd}}

Removing the mini_http package

{{Cmd|apk del mini_httpd}}

==Configure Lighttpd==
The configuration of lighttpd needs to be modified.

{{Cmd|nano /etc/lighttpd/lighttpd.conf}}

Uncomment this section and adjust the path so 'ssl.pemfile' points to where our cert/key pair is stored. Or copy the example below into your configuration file if you saved it to /etc/lighttpd/server.pem.
<pre>
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/server.pem"
</pre>

You'll also want to set the server to listen on port 443. Replace this:
server.port = 80
with this:
server.port = 443

Restart lighttpd

{{Cmd|rc-service lighttpd restart}}

== Security ==

=== BEAST attack, CVE-2011-3389 ===
To help mitigate the BEAST attack add the following to your configuration:

#### Mitigate BEAST attack:

# A stricter base cipher suite. For details see:
# http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-3389
# or
# http://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-2011-3389

ssl.cipher-list = "ECDHE-RSA-AES256-SHA384:AES256-SHA256:RC4-SHA:RC4:HIGH:!MD5:!aNULL:!EDH:!AESGCM"
#
# Make the server prefer the order of the server side cipher suite instead of the client suite.
# This is necessary to mitigate the BEAST attack (unless you disable all non RC4 algorithms).
# This option is enabled by default, but only used if ssl.cipher-list is set.
ssl.honor-cipher-order = "enable"

# Mitigate CVE-2009-3555 by disabling client triggered renegotiation
# This option is enabled by default.
#
ssl.disable-client-renegotiation = "enable"
#

=== Perfect Forward Secrecy (PFS) ===

[https://en.wikipedia.org/wiki/Perfect_forward_secrecy Perfect Forward Secrecy] isn't perfect, but what it does mean is that an adversary who gains the private key of a server does not have the ability to decrypt every encrypted SSL/TLS session. Without it, an adversary can simply obtain the private key of a server and decrypt and and all SSL/TLS sessions using that key. This is a major security and privacy concern and so using PFS is probabky a good idea long term. It means that every session would have to be decrypted individually, regardless of the state (whether obtained by the adversary or otherwise).

Utlimately when choosing SSl/TLS ciphers it is the usual chose of security or usablilty? Increasing one usually decreases the other. Nonetheles, an example to prevent the BEAST attack and offer PFS is:

<pre>
ssl.cipher-list = "ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-RC4-SHA:ECDHE-RSA-RC4-SHA:ECDH-ECDSA-RC4-SHA:ECDH-RSA-RC4-SHA:ECDHE-RSA-AES256-SHA:RC4-SHA"
</pre>

[https://raymii.org/s/tutorials/Pass_the_SSL_Labs_Test_on_Lighttpd_%28Mitigate_the_CRIME_and_BEAST_attack_-_Disable_SSLv2_-_Enable_PFS%29.html Source]

{{Note|Interestingly the [https://en.wikipedia.org/wiki/Satan Hebrew for Satan] is adversary; does this mean the NSA is Satan?}}

== Other configurations ==
The following are example configs, they will likely need to be modified to suite your particular setup. Nonetheless they should provide an indication of how to implement the relevant configuration options.

=== redirecting HTTP to HTTPS ===
Any requests to the server via HTTP (TCP port 80 by default) will be redirected to HTTPS (port 443):

<pre>
server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Ensure mod_redirect is enabled!
server.modules = (
"mod_redirect",
)

$SERVER["socket"] == ":80" {
$HTTP["host"] =~ "(.*)" {
url.redirect = ( "^/(.*)" => "https://%1/$1" )
}
}

$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
## Make sure the line above points to your SSL cert/key pair!
}

</pre>

=== Serving both HTTP and HTTPS requests ===
Simple, just add in the SSL server port, enable the SSL engine and point to the relevant SSL cert/key pair:

<pre>

server.port = 80
server.username = "lighttpd"
server.groupname = "lighttpd"
server.document-root = "/var/www/localhost/htdocs"
server.errorlog = "/var/log/lighttpd/error.log"
dir-listing.activate = "enable"
index-file.names = ( "index.html" )
mimetype.assign = ( ".html" => "text/html", ".txt" => "text/plain", ".jpg" => "image/jpeg", ".png" => "image/png", "" => "application/octet-stream" )

## Below is HTTPS setup. Make sure to point at relevant cert/key pair for HTTPS to work!
$SERVER["socket"] == ":443" {
ssl.engine = "enable"
ssl.pemfile = "/etc/lighttpd/certs/www.example.com.pem"
}
</pre>

== More details ==
* [http://redmine.lighttpd.net/wiki/1/Docs:SSL Lighttpd documentation]

[[Category:Server]]
[[Category:Security]]