snort

package: snort

title: snort(8)

text:
# snort(8)

## NAME
Snort - open source network intrusion detection system

## SYNOPSIS
snort [-bCdDeEfHIMNOpqQsTUvVwWxXy?] [-A alert-mode ] [-B address-conversion-mask ] [-c rules-file ] [-F bpf-file ] [-g group-name ] [-G id ] [-h home-net ] [-i interface ] [-k checksum-mode ] [-K logging-mode ] [-l log-dir ] [-L bin-log-file ] [-m umask ] [-n packet-count ] [-P snap-length ] [-r tcpdump-file ] [-R name ] [-S variable=value ] [-t chroot_directory ] [-u user-name ] [-Z pathname ] [--logid id ] [--perfmon-file pathname ] [--pid-path pathname ] [--snaplen snap-length ] [--help ] [--version ] [--dynamic-engine-lib file ] [--dynamic-engine-lib-dir directory ] [--dynamic-detection-lib file ] [--dynamic-detection-lib-dir directory ] [--dump-dynamic-rules directory ] [--dynamic-preprocessor-lib file ] [--dynamic-preprocessor-lib-dir directory ] [--dynamic-output-lib file ] [--dynamic-output-lib-dir directory ] [--alert-before-pass ] [--treat-drop-as-alert ] [--treat-drop-as-ignore ] [--process-all-events ] [--enable-inline-test ] [--create-pidfile ] [--nolock-pidfile ] [--no-interface-pidfile ] [--disable-attribute-reload-thread ] [--pcap-single= tcpdump-file ] [--pcap-filter= filter ] [--pcap-list= list ] [--pcap-dir= directory ] [--pcap-file= file ] [--pcap-no-filter ] [--pcap-reset ] [--pcap-reload ] [--pcap-show ] [--exit-check count ] [--conf-error-out ] [--enable-mpls-multicast ] [--enable-mpls-overlapping-ip ] [--max-mpls-labelchain-len ] [--mpls-payload-type ] [--require-rule-sid ] [--daq type ] [--daq-mode mode ] [--daq-var name=value ] [--daq-dir dir ] [--daq-list [dir] ] [--dirty-pig ] [--cs-dir dir ] [--ha-peer ] [--ha-out file ] [--ha-in file ] expression

## DESCRIPTION
Snort is an open source network intrusion detection system, capable of performing real-time traffic analysis and packet logging on IP networks. It can perform protocol analysis, content searching/matching and can be used to detect a variety of attacks and probes, such as buffer overflows, stealth port scans, CGI attacks, SMB probes, OS fingerprinting attempts, and much more. Snort uses a flexible rules language to describe traffic that it should collect or pass, as well as a detection engine that utilizes a modular plugin architecture. Snort also has a modular real-time alerting capability, incorporating alerting and logging plugins for syslog, a ASCII text files, UNIX sockets or XML.

Snort has three primary uses. It can be used as a straight packet sniffer like tcpdump(1), a packet logger (useful for network traffic debugging, etc), or as a full blown network intrusion detection system.

Snort logs packets in tcpdump(1) binary format or in Snort's decoded ASCII format to a hierarchy of logging directories that are named based on the IP address of the "foreign" host.

## OPTIONS
-A alert-mode

Alert using the specified alert-mode. Valid alert modes include fast, full, none, and unsock. Fast writes alerts to the default "alert" file in a single-line, syslog style alert message. Full writes the alert to the "alert" file with the full decoded header as well as the alert message. None turns off alerting. Unsock is an experimental mode that sends the alert information out over a UNIX socket to another process that attaches to that socket.

-b

Log packets in a tcpdump(1) formatted file. All packets are logged in their native binary state to a tcpdump formatted log file named with the snort start timestamp and "snort.log". This option results in much faster operation of the program

since it doesn't have to spend time in the packet binary->text converters. Snort can keep up pretty well with 100Mbps networks in '-b' mode. To choose an alternate name for the binary log file, use the '-L' switch.

-B address-conversion-mask

Convert all IP addresses in home-net to addresses specified by address-conversion-mask. Used to obfuscate IP addresses within binary logs. Specify home-net with the '-h' switch. Note this is not the same as $HOME_NET.

-c config-file

Use the rules located in file config-file.

-C

Print the character data from the packet payload only (no hex).

-d

Dump the application layer data when displaying packets in verbose or packet logging mode.

-D

Run Snort in daemon mode. Alerts are sent to /var/log/snort/alert unless otherwise specified.

-e

Display/log the link layer packet headers.

-E

*WIN32 ONLY* Log alerts to the Windows Event Log.

-f

Activate PCAP line buffering

-F bpf-file

Read BPF filters from bpf-file. This is handy for people running Snort as a SHADOW replacement or with a love Of super complex BPF filters. See the "expressions" section of this man page for more info on writing BPF filters.

-g group

Change the group/GID Snort runs under to group after initialization. This switch allows Snort to drop root privileges after it's initialization phase has completed as a security measure.

-G id

Use id as a base event ID when logging events.

-h home-net

Set the "home network" to home-net. The format of this address variable is a network prefix plus a CIDR block, such as 192.168.1.0/24. Once this variable is set, all decoded packet logging will be done relative to the home network address space. This is useful because of the way that Snort formats its ASCII log data. With this value set to the local network, all decoded output will be logged into decode directories with the address of the foreign computer as the directory name, which is very useful during traffic analysis. This option does not change "$HOME_NET" in IDS mode.

-H

Force hash tables to be deterministic instead of using a random number generator for the seed & scale. Useful for testing and generating repeatable results with the same traffic.

-i interface

Sniff packets on interface.

-I

Print out the receiving interface name in alerts.

-k checksum-mode

Tune the internal checksum verification functionality with alert-mode. Valid checksum modes include all, noip, notcp, noudp, noicmp, and none. All activates checksum verification for all supported protocols. Noip turns off IP checksum verification, which is handy if the gateway router is already dropping packets that fail their IP checksum checks. Notcp turns off TCP checksum verification, all other checksum modes are on. noudp turns off UDP checksum verification. Noicmp turns off ICMP checksum verification. None turns off the entire checksum verification subsystem.

-K logging-mode

Select a packet logging mode. The default is pcap. logging-mode. Valid logging modes include pcap, ascii, and none. Pcap logs packets through the pcap library into pcap (tcpdump) format. Ascii logs packets in the old "directories and files" format with packet printouts in each file. None Turns off packet logging.

-l log-dir

Set the output logging directory to log-dir. All plain text alerts and packet logs go into this directory. If this option is not specified, the default logging directory is set to /var/log/snort.

-L binary-log-file

Set the filename of the binary log file to binary-log-file. If this switch is not used, the default name is a timestamp for the time that the file is created plus "snort.log".

-m umask

Set the file mode creation mask to umask

-M

Log console messages to syslog when not running daemon mode. Using both -D and -M will send all messages to syslog including e.g. SIGUSR1 dump packet stats. This switch has no impact on logging of alerts.

-n packet-count

Process packet-count packets and exit.

-N

Turn off packet logging. The program still generates alerts normally.

-O

Obfuscate the IP addresses when in ASCII packet dump mode. This switch changes the IP addresses that get printed to the screen/log file to "xxx.xxx.xxx.xxx". If the homenet address switch is set (-h), only addresses on the homenet will be obfuscated while non- homenet IPs will be left visible. Perfect for posting to your favorite security mailing list!

-p

Turn off promiscuous mode sniffing.

-P snap-length

Set the packet snaplen to snap-length. By default, this is set to 1514.

-q

Quiet operation. Don't display banner and initialization information. In daemon mode, banner and initialization information is not logged to syslog.

-Q

Enable inline mode operation.

-r tcpdump-file

Read the tcpdump-formatted file tcpdump-file. This will cause Snort to read and process the file fed to it. This is useful if, for instance, you've got a bunch of SHADOW files that you want to process for content, or even if you've got a bunch of reassembled packet fragments which have been written into a tcpdump formatted file.

-R name

Use name as a suffix to the snort pidfile.

-s

Send alert messages to syslog. On linux boxen, they will appear in /var/log/secure, /var/log/messages on many other platforms.

-S variable=value

Set variable name "variable" to value "value". This is useful for setting the value of a defined variable name in a Snort rules file to a command line specified value. For instance, if you define a HOME_NET variable name inside of a Snort rules file, you can set this value from it's predefined value at the command line.

-t chroot

Changes Snort's root directory to chroot after initialization. Please note that all log/alert filenames are relative to the chroot directory if chroot is used.

-T

Snort will start up in self-test mode, checking all the supplied command line switches and rules files that are handed to it and indicating that everything is ready to proceed. This is a good switch to use if daemon mode is going to be used, it verifies that the Snort configuration that is about to be used is valid and won't fail at run time. Note, Snort looks for either /etc/snort.conf or ./snort.conf. If your config lives elsewhere, use the -c option to specify a valid config-file.

-u user

Change the user/UID Snort runs under to user after initialization.

-U

Changes the timestamp in all logs to be in UTC

-v

Be verbose. Prints packets out to the console. There is one big problem with verbose mode: it's slow. If you are doing IDS work with Snort, don't use the '-v' switch, you WILL drop packets.

-V

Show the version number and exit.

-w

Show management frames if running on an 802.11 (wireless) network.

-W

*WIN32 ONLY* Enumerate the network interfaces available.

-x

Exit if Snort configuration problems occur such as duplicate gid/sid or flowbits without Stream5.

-X

Dump the raw packet data starting at the link layer. This switch overrides the '-d' switch.

-y

Include the year in alert and log files

-Z pathname

Set the perfmonitor preprocessor path/filename to pathname.

-?

Show the program usage statement and exit.

--logid id

Same as -G.

--perfmon-file pathname

Same as -Z.

--pid-path directory

Specify the directory for the Snort PID file.

--snaplen snap-length

Same as -P.

--help

Same as -?

--version

Same as -V

--dynamic-engine-lib file

Load a dynamic detection engine shared library specified by file.

--dynamic-engine-lib-dir directory

Load all dynamic detection engine shared libraries specified from directory.

--dynamic-detection-lib file

Load a dynamic detection rules shared library specified by file.

--dynamic-detection-lib-dir directory

Load all dynamic detection rules shared libraries specified from directory.

--dump-dynamic-rules directory

Create stub rule files from all loaded dynamic detection rules libraries. Files will be created in directory. This is required to be done prior to running snort using those detection rules and the generated rules files must be included in snort.conf.

--dynamic-preprocessor-lib file

Load a dynamic preprocessor shared library specified by file.

--dynamic-preprocessor-lib-dir directory

Load all dynamic preprocessor shared libraries specified from directory.

--alert-before-pass

Process alert, drop, sdrop, or reject before pass. Default is pass before alert, drop, etc.

--treat-drop-as-alert

Converts drop, sdrop, and reject rules into alert rules during startup.

--treat-drop-as-ignore

Use drop, sdrop, and reject rules to ignore session traffic when not inline.

--process-all-events

Process all triggered events in group order, per Rule Ordering configuration. Default stops after first group.

--enable-inline-test

Enable Inline-Test Mode Operation.

--pid-path directory

Specify the path for Snort's PID file.

--create-pidfile

Create PID file, even when not in Daemon mode.

--nolock-pidfile

Do not try to lock Snort PID file.

--no-interface-pidfile

Do not include the interface name in Snort PID file

--pcap-single=tcpdump-file

Same as -r. Added for completeness.

--pcap-filter=filter

Shell style filter to apply when getting pcaps from file or directory. This filter will apply to any --pcap-file or --pcap-dir arguments following. Use --pcap-no-filter to delete filter for following --pcap-file or --pcap-dir arguments or specify --pcap-filter again to forget previous filter and to apply to following --pcap-file or --pcap-dir arguments.

--pcap-list="list"

A space separated list of pcaps to read.

--pcap-dir=directory

A directory to recurse to look for pcaps. Sorted in ascii order.

--pcap-file=file

File that contains a list of pcaps to read. Can specify path to pcap or directory to recurse to get pcaps.

--pcap-no-filter

Reset to use no filter when getting pcaps from file or directory.

--pcap-reset

If reading multiple pcaps, reset snort to post-configuration state before reading next pcap. The default, i.e. without this option, is not to reset state.

--pcap-show

Print a line saying what pcap is currently being read.

--exit-check=count

Signal termination after <count> callbacks from DAQ_Acquire(), showing the time it takes from signaling until DAQ_Stop() is called.

--conf-error-out

Same as -x.

--require-rule-sid

Require an SID for every rule to be correctly threshold all rules.

--daq <type>

Select packet acquisition module (default is pcap).

--daq-mode <mode>

Select the DAQ operating mode.

--daq-var <name=value>

Specify extra DAQ configuration variable.

--daq-dir <dir>

Tell Snort where to find desired DAQ.

--daq-list [<dir>]

List packet acquisition modules available in dir.

--cs-dir <dir>

Tell Snort to use control socket and create the socket in dir.

expression

selects which packets will be dumped. If no expression is given, all packets on the net will be dumped. Otherwise, only packets for which expression is `true' will be dumped. The expression consists of one or more primitives. Primitives usually consist of an id (name or number) preceded by one or more qualifiers. There are three different kinds of qualifier:

type

qualifiers say what kind of thing the id name or number refers to. Possible types are host, net and port. E.g., `host foo', `net 128.3', `port 20'. If there is no type qualifier, host is assumed.

dir

qualifiers specify a particular transfer direction to and/or from id. Possible directions are src, dst, src or dst and src and dst. E.g., `src foo', `dst net 128.3', `src or dst port ftp-data'. If there is no dir qualifier, src or dst is assumed. For `null' link layers (i.e. point to point protocols such as slip) the inbound and outbound qualifiers can be used to specify a desired direction.

proto

qualifiers restrict the match to a particular protocol. Possible protos are: ether, fddi, ip, arp, rarp, decnet, lat, sca, moprc, mopdl, tcp and udp. E.g., `ether src foo', `arp net 128.3', `tcp port 21'. If there is no proto qualifier, all protocols consistent with the type are assumed. E.g., `src foo' means `(ip or arp or rarp) src foo' (except the latter is not legal syntax), `net bar' means `(ip or arp or rarp) net bar' and `port 53' means `(tcp or udp) port 53'.

[`fddi' is actually an alias for `ether'; the parser treats them identically as meaning ``the data link level used on the specified network interface.'' FDDI headers contain Ethernet-like source and destination addresses, and often contain Ethernet-like packet types, so you can filter on these FDDI fields just as with the analogous Ethernet fields. FDDI headers also contain other fields, but you cannot name them explicitly in a filter expression.]

In addition to the above, there are some special `primitive' keywords that don't follow the pattern: gateway, broadcast, less, greater and arithmetic expressions. All of these are described below.

More complex filter expressions are built up by using the words and, or and not to combine primitives. E.g., `host foo and not port ftp and not port ftp-data'. To save typing, identical qualifier lists can be omitted. E.g., `tcp dst port ftp or ftp-data or domain' is exactly the same as `tcp dst port ftp or tcp dst port ftp-data or tcp dst port domain'.

Allowable primitives are:

dst host host

True if the IP destination field of the packet is host, which may be either an address or a name.

src host host

True if the IP source field of the packet is host.

host host

True if either the IP source or destination of the packet is host. Any of the above host expressions can be prepended with the keywords, ip, arp, or rarp as in:

```
ip host host
```

which is equivalent to:

```
ether proto \ip and host host
```

If host is a name with multiple IP addresses, each address will be checked for a match.

ether dst ehost

True if the ethernet destination address is ehost. Ehost may be either a name from /etc/ethers or a number (see ethers(3N) for numeric format).

ether src ehost

True if the ethernet source address is ehost.

ether host ehost

True if either the ethernet source or destination address is ehost.

gateway host

True if the packet used host as a gateway. I.e., the ethernet source or destination address was host but neither the IP source nor the IP destination was host. Host must be a name and must be found in both /etc/hosts and /etc/ethers. (An equivalent expression is

```
ether host ehost and not host host
```

which can be used with either names or numbers for host / ehost.)

dst net net

True if the IP destination address of the packet has a network number of net. Net may be either a name from /etc/networks or a network number (see networks(4) for details).

src net net

True if the IP source address of the packet has a network number of net.

net net

True if either the IP source or destination address of the packet has a network number of net.

net net mask mask

True if the IP address matches net with the specific netmask. May be qualified with src or dst.

net net/len

True if the IP address matches net a netmask len bits wide. May be qualified with src or dst.

dst port port

True if the packet is ip/tcp or ip/udp and has a destination port value of port. The port can be a number or a name used in /etc/services (see tcp(4P) and udp(4P)). If a name is used, both the port number and protocol are checked. If a number or ambiguous name is used, only the port number is checked (e.g., dst port 513 will print both tcp/login traffic and udp/who traffic, and port domain will print both tcp/domain and udp/domain traffic).

src port port

True if the packet has a source port value of port.

port port

True if either the source or destination port of the packet is port. Any of the above port expressions can be prepended with the keywords, tcp or udp, as in:

```
tcp src port port
```

which matches only tcp packets whose source port is port.

less length

True if the packet has a length less than or equal to length. This is equivalent to:

```
len <= length.
```

greater length

True if the packet has a length greater than or equal to length. This is equivalent to:

```
len >= length.
```

ip proto protocol

True if the packet is an ip packet (see ip(4P)) of protocol type protocol. Protocol can be a number or one of the names icmp, igrp, udp, nd, or tcp. Note that the identifiers tcp, udp, and icmp are also keywords and must be escaped via backslash (\), which is \\ in the C-shell.

ether broadcast

True if the packet is an ethernet broadcast packet. The ether keyword is optional.

ip broadcast

True if the packet is an IP broadcast packet. It checks for both the all-zeroes and all-ones broadcast conventions, and looks up the local subnet mask.

ether multicast

True if the packet is an ethernet multicast packet. The ether keyword is optional. This is shorthand for `ether[0] & 1 != 0'.

ip multicast

True if the packet is an IP multicast packet.

ether proto protocol

True if the packet is of ether type protocol. Protocol can be a number or a name like ip, arp, or rarp. Note these identifiers are also keywords and must be escaped via backslash (\). [In the case of FDDI (e.g., `fddi protocol arp'), the protocol identification comes from the 802.2 Logical Link Control (LLC) header, which is usually layered on top of the FDDI header. Tcpdump assumes, when filtering on the protocol identifier, that all FDDI packets include an LLC header, and that the LLC header is in so-called SNAP format.]

decnet src host

True if the DECNET source address is host, which may be an address of the form ``10.123'', or a DECNET host name. [DECNET host name support is only available on Ultrix systems that are configured to run DECNET.]

decnet dst host

True if the DECNET destination address is host.

decnet host host

True if either the DECNET source or destination address is host.

ip, arp, rarp, decnet

Abbreviations for:

```
ether proto p
```

where p is one of the above protocols.

lat, moprc, mopdl

Abbreviations for:

```
ether proto p
```

where p is one of the above protocols. Note that Snort does not currently know how to parse these protocols.

tcp, udp, icmp

Abbreviations for:

```
ip proto p
```

where p is one of the above protocols.

expr relop expr

True if the relation holds, where relop is one of >, <, >=, <=, =, !=, and expr is an arithmetic expression composed of integer constants (expressed in standard C syntax), the normal binary operators [+, -, *, /, &, |], a length operator, and special packet data accessors. To access data inside the packet, use the following syntax:

```
proto [ expr : size ]
```

Proto is one of ether, fddi, ip, arp, rarp, tcp, udp, or icmp, and indicates the protocol layer for the index operation. The byte offset, relative to the indicated protocol layer, is given by expr. Size is optional and indicates the number of bytes in the field of interest; it can be either one, two, or four, and defaults to one. The length operator, indicated by the keyword len, gives the length of the packet. For example, `ether[0] & 1 != 0' catches all multicast traffic. The expression `ip[0] & 0xf != 5' catches all IP packets with options. The expression `ip[6:2] & 0x1fff = 0' catches only unfragmented datagrams and frag zero of fragmented datagrams. This check is implicitly applied to the tcp and udp index operations. For instance, tcp[0] always means the first byte of the TCP header, and never means the first byte of an intervening fragment.

Primitives may be combined using:

A parenthesized group of primitives and operators (parentheses are special to the Shell and must be escaped).

Negation (`!' or `not').

Concatenation (`&&' or `and').

Alternation (`||' or `or').

Negation has highest precedence. Alternation and concatenation have equal precedence and associate left to right. Note that explicit and tokens, not juxtaposition, are now required for concatenation.

If an identifier is given without a keyword, the most recent keyword is assumed. For example,

```
not host vs and ace
```

is short for

```
not host vs and host ace
```

which should not be confused with

```
not ( host vs or ace )
```

Expression arguments can be passed to Snort as either a single argument or as multiple arguments, whichever is more convenient. Generally, if the expression contains Shell metacharacters, it is easier to pass it as a single, quoted argument. Multiple arguments are concatenated with spaces before being parsed.

## READING PCAPS
Instead of having Snort listen on an interface, you can give it a packet capture to read. Snort will read and analyze the packets as if they came off the wire. This can be useful for testing and debugging Snort.

Read a single pcap

$ snort -r foo.pcap $ snort --pcap-single=foo.pcap

Read pcaps from a file

$ cat foo.txt foo1.pcap

foo2.pcap

/home/foo/pcaps

$ snort --pcap-file=foo.txt

This will read foo1.pcap, foo2.pcap and all files under /home/foo/pcaps. Note that Snort will not try to determine whether the files under that directory are really pcap files or not.

Read pcaps from a command line list

$ snort --pcap-list="foo1.pcap foo2.pcap foo3.pcap" This will read foo1.pcap, foo2.pcap and foo3.pcap.

Read pcaps under a directory

$ snort --pcap-dir="/home/foo/pcaps" This will include all of the files under /home/foo/pcaps.

Using filters

$ cat foo.txt foo1.pcap

foo2.pcap

/home/foo/pcaps

$ snort --pcap-filter="*.pcap" --pcap-file=foo.txt

$ snort --pcap-filter="*.pcap" --pcap-dir=/home/foo/pcaps

The above will only include files that match the shell pattern "*.pcap", in other words, any file ending in ".pcap".

$ snort --pcap-filter="*.pcap --pcap-file=foo.txt \

> --pcap-filter="*.cap" --pcap-dir=/home/foo/pcaps

In the above, the first filter "*.pcap" will only be applied to the pcaps in the file "foo.txt" (and any directories that are recursed in that file). The addition of the second filter "*.cap" will cause the first filter to be forgotten and then applied to the directory /home/foo/pcaps, so only files ending in ".cap" will be included from that directory.

$ snort --pcap-filter="*.pcap --pcap-file=foo.txt \

> --pcap-no-filter --pcap-dir=/home/foo/pcaps

In this example, the first filter will be applied to foo.txt, then no filter will be applied to the files found under /home/foo/pcaps, so all files found under /home/foo/pcaps will be included.

$ snort --pcap-filter="*.pcap --pcap-file=foo.txt \

> --pcap-no-filter --pcap-dir=/home/foo/pcaps \

> --pcap-filter="*.cap" --pcap-dir=/home/foo/pcaps2

In this example, the first filter will be applied to foo.txt, then no filter will be applied to the files found under /home/foo/pcaps, so all files found under /home/foo/pcaps will be included, then the filter "*.cap" will be applied to files found under /home/foo/pcaps2.

Resetting state

$ snort --pcap-dir=/home/foo/pcaps --pcap-reset The above example will read all of the files under /home/foo/pcaps, but after each pcap is read, Snort will be reset to a post-configuration state, meaning all buffers will be flushed, statistics reset, etc. For each pcap, it will be like Snort is seeing traffic for the first time.

Printing the pcap

$ snort --pcap-dir=/home/foo/pcaps --pcap-show The above example will read all of the files under /home/foo/pcaps and will print a line indicating which pcap is currently being read.

## RULES
Snort uses a simple but flexible rules language to describe network packet signatures and associate them with actions. The current rules document can be found at http://www.snort.org/snort-rules.

## NOTES
The following signals have the specified effect when sent to the daemon process using the kill(1) command:

SIGHUP

Causes the daemon to close all opened files and restart. Please note that this will only work if the full pathname is used to invoke snort in daemon mode, otherwise snort will just exit with an error message being sent to syslogd(8).

SIGUSR1

Causes the program to dump its current packet statistical information to the console or syslogd(8) if in daemon mode.

SIGUSR2

Causes the program to rotate Perfmonitor statistical information to the console or syslogd(8) if in daemon mode.

SIGURG

Causes the program to reload attribute table.

SIGCHLD

Used internally.

Please refer to manual for more details. Any other signal might cause the daemon to close all opened files and exit.

## HISTORY
Snort has been freely available under the GPL license since 1998.

## DIAGNOSTICS
Snort returns a 0 on a successful exit, 1 if it exits on an error.

## BUGS
After consulting the BUGS file included with the source distribution, send bug reports to snort-devel@lists.snort.org

## AUTHOR
Martin Roesch <roesch@snort.org>

## SEE ALSO
tcpdump(1), pcap(3)


squid

package: squid

title: squid(8)

summary: HTTP web proxy caching server

text:
# squid(8)

## NAME
squid - HTTP web proxy caching server

## SYNOPSIS
squid [-dhisrvzCFNRSVYX] [--foreground] [-l facility ] [-f config-file ] [-[au] port ] [-k signal ] [-n service-name ] [-O command-line ]

## DESCRIPTION
squid is a high-performance proxy caching server for web clients, supporting FTP, ICAP, ICP, HTCP and HTTP data objects. Unlike traditional caching software, Squid handles all requests in a single, non-blocking process.

Squid keeps meta data and especially hot objects cached in RAM, caches DNS lookups, supports non-blocking DNS lookups, and implements negative caching of failed requests.

Squid supports SSL, extensive access controls, and full request logging. By using the lightweight Internet Cache Protocols ICP, HTCP or CARP, Squid caches can be arranged in a hierarchy or mesh for additional bandwidth savings.

Squid consists of a main server program squid , some optional programs for custom processing and authentication, and some management and client tools. When squid starts up, it spawns a configurable number of helper processes, each of which can perform parallel lookups. This reduces the amount of time the cache waits for results.

Squid is derived from the ARPA-funded Harvest Project.

This manual page only lists the command line arguments. For details on how to configure Squid see the file /etc/squid/squid.conf.documented, the Squid wiki FAQ and examples at https://wiki.squid-cache.org/ , or the configuration manual on the Squid home page http://www.squid-cache.org/Doc/config/

## OPTIONS
-a port

Specify HTTP port number where Squid should listen for requests, in addition to any http_port specifications in squid.conf

-C

Do not catch fatal signals.

-d level

Write debugging to stderr also.

-f file

Use the given config-file instead of /etc/squid/squid.conf . If the file name starts with a ! or | then it is assumed to be an external command or command line. Can for example be used to pre-process the configuration before it is being read by Squid. To facilitate this Squid also understands the common #line notion to indicate the real source file.

-F

Don't serve any requests until store is rebuilt.

-h

Print help message.

-i

Install as a Windows Service (see -n option).

-k reconfigure | rotate | shutdown | interrupt | kill | debug | check | parse

Parse configuration file, then send signal to running copy (except -k parse ) and exit.

-l facility

Use specified syslog facility. Implies -s

-n name

Specify Windows Service name to use for service operations, default is: Squid

-N

No daemon mode.

--foreground

Parent process does not exit until its children have finished. It has no effect with -N which does not fork/exit at startup.

--kid roleID

Play a given SMP kid process role, with a given ID. Do not use this option. It is meant for the master process use only.

-O options

Set Windows Service Command line options in Registry.

-r

Remove a Windows Service (see -n option).

-R

Do not set REUSEADDR on port.

-s

Enable logging to syslog. Also configurable in /etc/squid/squid.conf

-S

Double-check swap during rebuild.

-u port

Specify ICP port number (default: 3130), disable with 0.

-v

Print version and build details.

-X

Force full debugging.

-Y

Only return UDP_HIT or UDP_MISS_NOFETCH during fast reload.

-z

Create missing swap directories and other missing cache_dir structures, then exit. All cache_dir types create the configured top-level directory if it is missing. Other actions are type-specific. For example, ufs-based storage systems create missing L1 and L2 directories while Rock creates the missing database file.

This option does not enable validation of any present swap structures. Its focus is on creation of missing pieces. If nothing is missing, squid -z just exits. If you suspect cache_dir corruption, you must delete the top-level cache_dir directory before running squid -z.

By default, squid -z runs in daemon mode (so that configuration macros and other SMP features work as expected), returning control to the caller before cache_dirs are fully initialized. If run from init scripts or daemon managers, the caller often needs to wait for the initialization to complete before proceeding further. Use --foreground option to prevent premature exits. To disable daemon mode, use -N option.

## FILES
Squid configuration files located in /etc/squid/:

squid.conf

The main configuration file. You must initially make changes to this file for squid to work. For example, the default configuration only allows access from RFC private LAN networks. Some packaging distributions block even that.

squid.conf.default

Reference copy of the configuration file. Always kept up to date with the version of Squid you are using.

Use this to look up the default configuration settings and syntax after upgrading.

squid.conf.documented

Reference copy of the configuration file. Always kept up to date with the version of Squid you are using.

Use this to read the documentation for configuration options available in your build of Squid. The online configuration manual is also available for a full reference of options. seehttp://www.squid-cache.org/Doc/config/

msntauth.conf

The main configuration file for the Sample MSNT authenticator.

errorpage.css

CSS Stylesheet to control the display of generated error pages. Use this to set any company branding you need, it will apply to every language Squid provides error pages for.

Some files also located elsewhere:

/etc/squid/mime.conf (mime_table)

MIME type mappings for FTP gatewaying

/usr/share/squid/errors

Location of Squid error pages and templates.

## AUTHOR
Squid was written over many years by a changing team of developers and maintained in turn by Duane Wessels <duane@squid-cache.org> Henrik Nordstrom <hno@squid-cache.org> Amos Jeffries <amosjeffries@squid-cache.org>

With contributions from many others in the Squid community. see CONTRIBUTORS for a full list of individuals who contributed code. see CREDITS for a list of major code contributing copyright holders.

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
basic_pam_auth (8), basic_ldap_auth (8), ext_ldap_group_acl (8), ext_session_acl (8), ext_unix_group_acl (8),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


package: squid-helpers

title: basic_db_auth(8)

summary: Database auth helper for Squid

text:
# basic_db_auth(8)

## NAME

```
 basic_db_auth - Database auth helper for Squid
```

## SYNOPSIS

```
 basic_db_auth [options]
```

## DESCRIPTION
This program verifies username & password to a database

## OPTIONS
--debug

Write debug info to stderr.

--dsn

Database DSN. Default "DBI:mysql:database=squid"

--user

Database User

--password

Database password

--table

Database table. Default "passwd".

--usercol

Username column. Default "user".

--passwdcol

Password column. Default "password".

--cond

Condition, defaults to enabled=1. Specify 1 or "" for no condition If you use --joomla flag, this condition will be changed to block=0

--plaintext

Database contains plain-text passwords

--md5

Database contains unsalted MD5 passwords

--sha1

Database contains unsalted SHA1 passwords

--salt

Selects the correct salt to evaluate passwords

--persist

Keep a persistent database connection open between queries.

--joomla

Tells helper that user database is Joomla DB. So their unusual salt hashing is understood.

## AUTHOR
This program was written by Henrik Nordstrom <henrik@henriknordstrom.net> and Luis Daniel Lucio Quiroz <dlucio@okay.com.mx>

This manual was written by Henrik Nordstrom <henrik@henriknordstrom.net>

## COPYRIGHT

```
 * Copyright (C) 1996-2026 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
```

Copyright (C) 2007 Henrik Nordstrom <henrik@henriknordstrom.net> Copyright (C) 2010 Luis Daniel Lucio Quiroz <dlucio@okay.com.mx> (Joomla support) This program is free software. You may redistribute copies of it under the terms of the GNU General Public License version 2, or (at your opinion) any later version.

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid (8), GPL (7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: basic_getpwnam_auth(8)

summary: Local Users auth helper for Squid

text:
# basic_getpwnam_auth(8)

## NAME
basic_getpwnam_auth - Local Users auth helper for Squid

## SYNOPSIS
basic_getpwnam_auth

## DESCRIPTION
basic_getpwnam_auth allows Squid to authenticate any local user accounts to validate the user name and password of Basic HTTP authentication.

It uses getpwnam() and getspnam() routines for authentication.

This has the following advantages over the NCSA module:

- Allows authentication of all known local users

- Allows authentication through nsswitch.conf

- Can handle NIS(+) requests

- Can handle LDAP requests

- Can handle PAM requests

## CONFIGURATION
auth_param basic program /path/to/basic_getpwnam_auth

auth_param basic children concurrency=1

When used for authenticating to local UNIX shadow password databases the program must be running as root or else it won't have sufficient permissions to access the user password database. Such use of this program is not recommended, but if you absolutely need to then make the program setuid root

chown root basic_getpwnam_auth

chmod u+s basic_getpwnam_auth

Please note that in such configurations it is also strongly recommended that the program is moved into a directory where normal users cannot access it, as this mode of operation will allow any local user to brute-force other users passwords. Also note the program has not been fully audited and the author cannot be held responsible for any security issues due to such installations.

## AUTHOR
This program was written by Erik Hofman <erik.hofman@a1.nl> Robin Elfrink <robin@a1.nl> Giancarlo Razzolini <linux-fan@onda.com.br>

Based on original code by Jon Thackray <jrmt@uk.gdscorp.com>.

This manual was written by Amos Jeffries <amosjeffries@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), basic_pam_auth(8), basic_ncsa_auth(8), basic_ldap_auth(8), basic_nis_auth(8), chown(1), chmod(1), nsswitch.conf(5), getpwnam(3), getspnam(3), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: basic_ldap_auth(8)

summary: LDAP authentication helper for Squid

text:
# basic_ldap_auth(8)

## NAME
basic_ldap_auth - LDAP authentication helper for Squid

## SYNOPSIS
basic_ldap_auth -b " base DN " [-u attribute ] [ options ] [ LDAP server name [: port ]| URI ]...

basic_ldap_auth -b " base DN " -f " LDAP search filter " [ options ] [ LDAP server name [: port ]| URI ]...

## DESCRIPTION
basic_ldap_auth allows Squid to connect to a LDAP directory to validate the user name and password of Basic HTTP authentication. LDAP options are specified as parameters on the command line, while the username(s) and password(s) to be checked against the LDAP directory are specified on subsequent lines of input to the helper, one username/password pair per line separated by a space.

As expected by the basic authentication construct of Squid, after specifying a username and password followed by a new line, this helper will produce either OK or ERR on the following line to show if the specified credentials are correct according to the LDAP directory.

The program has two major modes of operation. In the default mode of operation the users DN is constructed using the base DN and user attribute. In the other mode of operation a search filter is used to locate valid user DN's below the base DN.

## OPTIONS
-b basedn

REQUIRED. Specifies the base DN under which the users are located.

-f filter

LDAP search filter to locate the user DN. Required if the users are in a hierarchy below the base DN, or if the login name is not what builds the user specific part of the users DN.

The search filter can contain up to 15 occurrences of %s which will be replaced by the username, as in "uid=%s" for RFC2037 directories. For a detailed description of LDAP search filter syntax see RFC2254.

Will crash if other % values than %s are used, or if more than 15 %s are used.

-u userattr

Specifies the name of the DN attribute that contains the username/login. Combined with the base DN to construct the users DN when no search filter is specified ( -f option). Defaults to uid

Note: This can only be done if all your users are located directly under the same position in the LDAP tree and the login name is used for naming each user object. If your LDAP tree does not match these criteria or if you want to filter who are valid users then you need to use a search filter to search for your users DN ( -f option).

-U passwordattr

Use ldap_compare instead of ldap_simple_bind to verify the users password. passwordattr is the LDAP attribute storing the users password.

-s base|one|sub

Search scope when performing user DN searches specified by the -f option. Defaults to sub

base object only,

one level below the base object or

subtree below the base object

-D binddn -w password

The DN and password to bind as while performing searches. Required by the -f flag if the directory does not allow anonymous searches.

As the password needs to be printed in plain text in your Squid configuration it is strongly recommended to use a account with minimal associated privileges. This to limit the damage in case someone could get hold of a copy of your Squid configuration file.

-D binddn -W secretfile

The DN and the name of a file containing the password to bind as while performing searches.

Less insecure version of the former parameter pair with two advantages: The password does not occur in the process listing, and the password is not being compromised if someone gets the squid configuration file without getting the secretfile.

-P

Use a persistent LDAP connection. Normally the LDAP connection is only open while validating a username to preserve resources at the LDAP server. This option causes the LDAP connection to be kept open, allowing it to be reused for further user validations. Recommended for larger installations.

-O

Only bind once per LDAP connection. Some LDAP servers do not allow re-binding as another user after a successful ldap_bind. The use of this option always opens a new connection for each login attempt. If combined with the -P option for persistent LDAP connection then the connection used for searching for the user DN is kept persistent but a new connection is opened to verify each users password once the DN is found.

-R

Do not follow referrals

-a never|always|search|find

when to dereference aliases. Defaults to never

never dereference aliases (default), always dereference aliases, only during a search or only to find the base object.

-H ldap_uri

Specify the LDAP server to connect to by LDAP URI (requires OpenLDAP libraries). Servers can also be specified last on the command line.

-h ldap_server

Specify the LDAP server to connect to. Servers can also be specified last on the command line.

-p ldap_port

Specify an alternate TCP port where the LDAP server is listening if other than the default LDAP port 389. Can also be specified within the server specification by using servername:port syntax.

-v 2|3

LDAP protocol version. Defaults to 3 if not specified.

-Z

Use TLS encryption

-S certpath

Enable LDAP over SSL (requires Netscape LDAP API libraries)

-c connect_timeout

Specify timeout used when connecting to LDAP servers (requires Netscape LDAP API libraries)

-t search_timeout

Specify time limit on LDAP search operations

-d

Debug mode where each step taken will get reported in detail. Useful for understanding what goes wrong if the results is not what is expected.

## CONFIGURATION
For directories using the RFC2307 layout with a single domain, all you need to specify is usually the base DN under where your users are located and the server name:

basic_ldap_auth -b ou=people,dc=your,dc=domain ldapserver

If you have sub-domains then you need to use a search filter approach to locate your user DNs as these can no longer be constructed directly from the base DN and login name alone:

basic_ldap_auth -b dc=your,dc=domain -f uid=%s ldapserver

And similarly if you only want to allow access to users having a specific attribute

basic_ldap_auth -b dc=your,dc=domain -f (&(uid=%s)(specialattribute=value)) ldapserver

Or if the user attribute of the user DN is cn instead of uid and you do not want to have to search for the users then you could use something like the following example for Active Directory:

basic_ldap_auth -u cn -b cn=Users,dc=your,dc=domain ldapserver

If you want to search for the user DN and your directory does not allow anonymous searches then you must also use the -D and -w flags to specify a user DN and password to log in as to perform the searches, as in the following complex Active Directory example

basic_ldap_auth -P -R -b dc=your,dc=domain -D cn=squid,cn=users,dc=your,dc=domain -w secretsquidpassword -f (&(userPrincipalName=%s)(objectClass=Person)) activedirectoryserver

NOTE: When constructing search filters it is strongly recommended to test the filter using ldapsearch before you attempt to use basic_ldap_auth. This to verify that the filter matches what you expect.

## AUTHOR
This program is written by Glenn Newton <gnewton@wapiti.cisti.nrc.ca> Henrik Nordstrom <hno@squid-cache.org> This manual is written by Henrik Nordstrom <hno@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

Or to your favorite LDAP list/friend if the question is more related to LDAP than Squid.

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), ldapsearch(1), GPL(7),

Your favorite LDAP documentation.

RFC2254 - The String Representation of LDAP Search Filters,

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: basic_ncsa_auth(8)

text:
# basic_ncsa_auth(8)

## NAME
basic_ncsa_auth - NCSA httpd-style password file authentication helper for Squid

## SYNOPSIS
basic_ncsa_auth passwd file

## DESCRIPTION
basic_ncsa_auth allows Squid to read and authenticate user and password information from an NCSA/Apache httpd-style password file when using basic HTTP authentication.

This password file can be manipulated using htpasswd.

This authenticator accepts:

* Blowfish - for passwords 72 characters or less in length.

* SHA256 - with salting and magic strings.

* SHA512 - with salting and magic strings.

* MD5 - with optional salt and magic strings.

* DES - for passwords 8 characters or less in length. NOTE: Blowfish and SHA algorithms require system-specific support.

## OPTIONS
The only parameter is the password file. It must have permissions to be read by the user that Squid is running as.

## CONFIGURATION
basic_ncsa_auth /etc/squid/squid.pass

basic_ncsa_auth must have access to the password file to be executed.

## KNOWN ISSUES
DES functionality (used by htpasswd by default) silently truncates passwords to 8 characters. Allowing login with password values shorter than the one desired. This authenticator will reject login with long passwords when using DES.

## AUTHOR
This manual was written by Amos Jeffries <amosjeffries@squid-cache.org>

Based on original documentation by Rodrigo Rubira Branco <rrbranco@br.ibm.com>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This file is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this file; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), htpasswd(1), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: basic_pam_auth(8)

text:
# basic_pam_auth(8)

## NAME
basic_pam_auth - PAM Basic authentication helper for Squid

## SYNOPSIS
basic_pam_auth [-n service name TTL ] [-o] [-1]

## DESCRIPTION
basic_pam_auth allows Squid to connect to a mostly any available PAM database to validate the user name and password of Basic HTTP authentication.

## OPTIONS
-s service-name

Specifies the PAM service name Squid uses, defaults to squid

-t TTL

Enables persistent PAM connections where the connection to the PAM database is kept open and reused for new logins. The TTL specifies how long the connection will be kept open (in seconds). Default is to not keep PAM connections open. Please note that the use of persistent PAM connections is slightly outside the PAM specification and may not work with all PAM configurations.

-o

Do not perform the PAM account management group (account expiration etc)

## CONFIGURATION
The program needs a PAM service to be configured in /etc/pam.conf or /etc/pam.d/squid

The default service name is squid , and the program makes use of the auth and account management groups to verify the password and the accounts validity.

For details on how to configure PAM services, see the PAM documentation for your system. This manual does not cover PAM configuration details.

## NOTES
When used for authenticating to local UNIX shadow password databases the program must be running as root or else it won't have sufficient permissions to access the user password database. Such use of this program is not recommended, but if you absolutely need to then make the program setuid root

chown root basic_pam_auth

chmod u+s basic_pam_auth

Please note that in such configurations it is also strongly recommended that the program is moved into a directory where normal users cannot access it, as this mode of operation will allow any local user to brute-force other users passwords. Also note the program has not been fully audited and the author cannot be held responsible for any security issues due to such installations.

## AUTHOR
This program and documentation was written by Henrik Nordstrom <hno@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

Squid basic_pam_auth and this manual is Copyright 1999,2002,2003 Henrik Nordstrom <hno@squid-cache.org> Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), pam(3), pam.conf(5), chown(1), chmod(1), GPL(7),

PAM Systems Administrator Guide

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: basic_radius_auth(8)

summary: Squid RADIUS authentication helper

text:
# basic_radius_auth(8)

## NAME
basic_radius_auth - Squid RADIUS authentication helper

## SYNOPSIS
basic_radius_auth -f config file

basic_radius_auth -h " server name " [-p port ] [-i identifier ] -w secret [-t timeout ]

## DESCRIPTION
basic_radius_auth allows Squid to connect to a RADIUS server to validate the user name and password of Basic HTTP authentication.

## OPTIONS
-f configfile

Specifies the path to a configuration file. See the CONFIGURATION section for details on the file content.

-h server

Alternative method of specifying the server to connect to

-p port

Specify another server port where the RADIUS server listens for requests if different from the default RADIUS port. Normally not specified.

-i identifier

Unique identifier identifying this Squid proxy to the RADIUS server. If not specified the IP address is used to identify the proxy.

-w secret

Alternative method of specifying the shared secret. Using the -f option with a configuration file is generally more secure and recommended.

-t timeout

RADIUS request timeout. Default is 10 seconds.

## CONFIGURATION
The configuration specifies how the helper connects to RADIUS. The file contains a list of directives (one per line). Lines beginning with a # are ignored.

server radiusserver

specifies the name or address of the RADIUS server to connect to.

secret somesecretstring

specifies the shared RADIUS secret.

identifier nameofserver

specifies what name the proxy should use to identify itself to the RADIUS server. This directive is optional.

port portnumber

Specifies the port number or service name where the helper should connect.

timeout seconds

Specifies the RADIUS request timeout.

## AUTHOR
This program is written by Marc van Selm <selm@cistron.nl> Henrik Nordstrom <hno@squid-cache.org>

With contributions from many others.

This manual was written by Henrik Nordstrom <hno@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

Or contact your favorite RADIUS list/friend if the question is more related to RADIUS than Squid.

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), GPL(7),

RFC2058 - Remote Authentication Dial In User Service (RADIUS)

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: basic_sasl_auth(8)

text:
# basic_sasl_auth(8)

## NAME
basic_sasl_auth - Basic Authentication using SASL (specifically the cyrus-sasl authentication method)

Version 1.0

## SYNOPSIS
basic_sasl_auth

## DESCRIPTION
basic_sasl_auth is an installed binary helper for Squid. SASL is configurable (somewhat like PAM). Each service authenticating against SASL identifies itself with an application name. Each application can be configured independently by the SASL administrator.

## CONFIGURATION
To configure the authentication method used the file basic_sasl_auth.conf can be placed in the appropriate location, usually /usr/lib/sasl.

The authentication database is defined by the pwcheck_method parameter. Only the PLAIN authentication mechanism is used.

Examples: pwcheck_method:sasldb use sasldb - the default if no conf file is installed. pwcheck_method:pam

- use PAM authentication database pwcheck_method:passwd

- use traditional /etc/passwd pwcheck_method:shadow

- use slightly less traditional /etc/shadow

Others methods may be supported by your cyrus-sasl implementation - consult your cyrus-sasl documentation for information.

Typically the authentication database ( /etc/sasldb , /etc/shadow , PAM ) can not be accessed by a normal user. You should use setuid/setgid and an appropriate user/group on the executable to allow the authenticator to access the appropriate password database. If the access to the database is not permitted then the authenticator will typically fail with "-1, generic error".

chown root.mail basic_sasl_auth

chmod ug+s basic_sasl_auth

If the application name basic_sasl_auth will also be used for the PAM service name if pwcheck_method:pam is chosen. And example PAM configuration file basic_sasl_auth.pam is also included.

## AUTHOR
This program was written by Ian Castle <ian.castle@coldcomfortfarm.net>

This manual was written by Ian Castle <ian.castle@coldcomfortfarm.net> Amos Jeffries <amosjeffries@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), SASL(3), PAM(7), passwd(1), shadow(5), chown(1), chmod(1), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: digest_file_auth(8)

text:
# digest_file_auth(8)

## NAME
digest_file_auth - File based digest authentication helper for Squid.

Version 1.1

## SYNOPSIS
digest_file_auth [-c] file

## DESCRIPTION
digest_file_auth is an installed binary authentication program for Squid. It handles digest authentication protocol and authenticates against a text file backend. This program will automatically detect the existence of a concurrency channel-ID and adjust appropriately. It may be used with any value 0 or above for the auth_param children concurrency= parameter.

## OPTIONS
-c

Accept digest hashed passwords rather than plaintext in the password file

## CONFIGURATION
Username database file format:

- comment lines are possible and should start with a '#';

- empty or blank lines are possible;

- plaintext entry format is username:password

- HA1 entry format is username:realm:HA1

To build a directory integrated backend, you need to be able to calculate the HA1 returned to squid. To avoid storing a plaintext password you can calculate MD5(username:realm:password) when the user changes their password, and store the tuple username:realm:HA1. then find the matching username:realm when squid asks for the HA1.

This implementation could be improved by using such a triple for the file format. However storing such a triple does little to improve security: If compromised the username:realm:HA1 combination is "plaintext equivalent" - for the purposes of digest authentication they allow the user access. Password synchronization is not tackled by digest - just preventing on the wire compromise.

## AUTHOR
This program was written by Robert Collins <robertc@squid-cache.org>

Based on prior work by Arjan de Vet <Arjan.deVet@adv.iae.nl>

This manual was written by Robert Collins <robertc@squid-cache.org> Amos Jeffries <amosjeffries@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_delayer_acl(8)

text:
# ext_delayer_acl(8)

## NAME

```
 delayer - Squid external ACL helper adding artificial delay to requests
```

## SYNOPSIS

```
 delayer [--help] [--debug] [--log file] [--wait msec]
```

## DESCRIPTION
Squid external acl helper; causes squid to delay responding to HTTP requests.

By carefully crafting the ACLs of a Squid setup it is possible to selectively delay requests received by a proxy. After the configured amount of time, it will always return "true".

## OPTIONS
--help or -h

Print help message to stdout

--debug or -d

Emit debugging output to STDERR and ultimately cache.log

--log /path/to/file or -l /path/to/file

Emit debugging output to specified file instead of STDERR. Also turns on debugging

--wait msec or -w msec

Delay each request by the specified amount of msec. Unless this option is specified, by default each submitted request will be delayed by half a second (500 msec).

## CONFIGURATION
To engage it, this snippet of configuration template can be used in squid.conf:

```
 external_acl_type delayer concurrency=100000 children-max=2 children-startup=1 children-idle=1 cache=10 %URI /path/to/delayer -w 200
 acl delay external delayer
 http_access allow acl1 acl2 acl3 delay !all
```

It is important that the acl referencing the delayer be the penultimate clause in the http_access line. It will cause delay to all requests that match all the preceding acls in the line. The !all clause at the end of the line will make it so that no traffic is authorized by this ACL, only the delay to evaluate the delay clause will be inserted before evaluating following http_access lines. It is also important to place the http_access line carefully in the sequence of all http_access_lines; it should be near the beginning, but be careful not to insert unwanted slow acls (especially proxy_auth).

It is possible to customize how delay is calculated for each request by modifying the "calc_delay" PERL function in the script, documentation on this is embedded in the source code comments.

## AUTHOR
This software is written by Francesco Chemolli <kinkie@squid-cache.org>

## COPYRIGHT

```
 * Copyright (C) 1996-2026 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 (C) 2014 Francesco Chemolli <kinkie@squid-cache.org>
 This program is free software. You may redistribute copies of it under the
 terms of the GNU General Public License version 2, or (at your opinion) any
 later version.
```

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid (8), GPL (7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_edirectory_userip_acl(8)

summary: Squid eDirectory IP Lookup Helper

text:
# ext_edirectory_userip_acl(8)

## NAME
ext_edirectory_userip_acl - Squid eDirectory IP Lookup Helper

Version 2.0

## SYNOPSIS
ext_edirectory_userip_acl [-h | --help | --usage]

ext_edirectory_userip_acl -H host -p port [-Z] [-P] [-v LDAP version ] -b basedn -s scope -D binddn -W bindpass -F filter [-G]

## DESCRIPTION
ext_edirectory_userip_acl is an installed binary.

This program has been written in order to solve the problems associated with running the Perl squid_ip_lookup.pl as a squid external helper.

The limitations of the Perl script involved memory/cpu utilization, speed, the lack of eDirectory 8.8 support, and IPv6 support.

## OPTIONS
-4

Force Addresses to be in IPv4 (0.0.0.0 format).

-6

Force Addresses to be in IPv6 (:: format).

-b base

Specify base DN. For example; o=ORG

-d

Write debug info to stderr.

-Dbinddn

Specify binding DN. For example; cn=squid,o=ORG

-F filter

Specify LDAP search filter. For example; (objectClass=User)

-G

Specify if LDAP search group is required. For example; groupMembership=

-h | --help | --usage

Display the binary help and command line syntax info using stderr.

-H host

Specify hostname or IP of server

-p port

Port number.

-P

Use persistent connections.

-t seconds

Timeout factor for persistent connections. Set to 0 for never timeout. Default is 60 seconds.

-s base|one|sub

search scope. Defaults to sub

base object only,

one level below the base object or

subtree below the base object

-u attribute

Set userid attribute . Default is cn

-v 1|2|3

Set LDAP version

-V

Display version information and exit.

-W password

Specify binding password

-Z

Enable TLS security.

## CONFIGURATION
external_acl_type IPUser %SRC /usr/sbin/ext_edirectory_userip_acl

acl edirectory_users_allowed external IPUser cn=Internet_Allowed,ou=ORG,o=BASE acl edirectory_users_denied external IPUser cn=Internet_Denied,ou=ORG,o=BASE

http_access deny edirectory_users_denied http_access allow edirectory_users_allowed http_access deny all

In this example, the Internet_Allowed and Internet_Denied are Groups that users may be used to control internet access, which can also be stacked against other ACL's. Use of the groups is optional, unless the '-G' option has been passed. Please note that you need to specify the full LDAP object for this, as shown above.

## KNOWN ISSUES
IPv6 support has yet to be tested in a real IPv6 environment, but the code is in place to read IPv6 networkAddress fields, please attempt this in a TESTING environment first. Please contact the author regarding IPv6 support development.

There is a known issue regarding Novell's Client for Windows, that is mostly fixed by using version 4.91 SP3+, with the 'Auto-Reconnect' feature not re-populating the networkAddress field in eDirectory.

I have also experienced an issue related to using NetWare 6.5 (SP6 and lower?) and connection licensing. It appears that whenever a server runs low on connection licenses, that it I sometimes does not populate the networkAddress fields correctly.

Majority of Proxy Authentication issues can be resolved by having the users' reboot if their networkAddress is not correct, or using basic_ldap_auth as a fallback. Check ConsoleOne, etc to verify their networkAddress fields to troubleshoot.

## AUTHOR
This program was written by Chad E. Naugle <chad.naugle@travimp.com>

This manual was written by Chad E. Naugle <chad.naugle@travimp.com> Amos Jeffries <amosjeffries@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
I STRONGLY RECOMMEND using the latest version of the Novell Client in all situations before seeking support! You may also need to make sure your servers have the latest service packs installed, and that your servers are properly synchronizing partitions.

Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), basic_ldap_auth(8), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_file_userip_acl(8)

text:
# ext_file_userip_acl(8)

## NAME
ext_file_userip_acl - Restrict users to certain IP addresses, using a text file backend.

Version 1.0

## SYNOPSIS
ext_file_userip_acl [-dh] [-f file name ]

## DESCRIPTION
ext_file_userip_acl is an installed binary. An external helper for the Squid external acl scheme.

It works by reading a pair composed by an IP address and an username on STDIN and matching it against a configuration file.

## OPTIONS
-d

Write debug info to stderr.

-f file

Configuration file to load.

-h

Display the binary help and command line syntax info using stderr.

## CONFIGURATION
The squid.conf configuration for the external ACL should be:

external_acl_type type-name %SRC %LOGIN /path/to/ext_file_userip_acl -f /path/to/config.file

If the helper program finds a matching username/ip in the configuration file, it returns OK , otherwise it returns ERR .

The configuration file format is as follows:

ip_addr[/netmask] username|@group|ALL|NONE

Where ip_addr is a dotted quad format IP address, the netmask must be in dotted quad format too.

When the second parameter is prefixed with an @ , the program will lookup the /etc/group file entry for the specified username.

There are other two directives, ALL and NONE , which mean "any user on this IP address may authenticate" or "no user on this IP address may authenticate".

## AUTHOR
This program was written by Rodrigo Campos <rodrigo@geekbunker.org>

This manual was written by Rodrigo Campos <rodrigo@geekbunker.org> Amos Jeffries <amosjeffries@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_ldap_group_acl(8)

summary: Squid LDAP external acl group helper

text:
# ext_ldap_group_acl(8)

## NAME
ext_ldap_group_acl - Squid LDAP external acl group helper

Version 2.18

## SYNOPSIS
ext_ldap_group_acl -b base-DN -f filter [ options ] [ server [ ':' port ] | URI ] ...

## DESCRIPTION
ext_ldap_group_acl allows Squid to connect to a LDAP directory to authorize users via LDAP groups. LDAP options are specified as parameters on the command line, while the username(s) and group(s) to be checked against the LDAP directory are specified on subsequent lines of input to the helper, one username/group pair per line separated by a space.

As expected by the external_acl_type construct of Squid, after specifying a username and group followed by a new line, this helper will produce either OK or ERR on the following line to show if the user is a member of the specified group.

The program operates by searching with a search filter based on the users user name and requested group, and if a match is found it is determined that the user belongs to the group.

## OPTIONS
-a never|always|search|find

When to dereference aliases. Defaults to 'never'

never dereference aliases (default), always dereference aliases, only during a search or only to find the base object

-b basedn

REQUIRED. Specifies the base DN under which the groups are located.

-B basedn

Specifies the base DN under which the users are located (if different)

-c connect_timeout

Specify timeout used when connecting to LDAP servers (requires Netscape LDAP API libraries)

-d

Debug mode where each step taken will get reported in detail. Useful for understanding what goes wrong if the result is not what was expected.

-D binddn -w password

The DN and password to bind as while performing searches. Required if the LDAP directory does not allow anonymous searches.

As the password needs to be printed in plain text in your Squid configuration and will be sent on the command line to the helper it is strongly recommended to use a account with minimal associated privileges. This to limit the damage in case someone could get hold of a copy of your Squid configuration file or extracts the password used from a process listing.

-D binddn -W secretfile

The DN and the name of a file containing the password to bind as while performing searches.

Less insecure version of the former parameter pair with two advantages: The password does not occur in the process listing, and the password is not being compromised if someone gets the squid configuration file without getting the secretfile.

-E certpath

Enable LDAP over SSL (requires Netscape LDAP API libraries)

-f filter

LDAP search filter used to search the LDAP directory for any matching group memberships. In the filter %u will be replaced by the user name (or DN if the -F or -u options are used) and %g by the requested group name.

-F filter

LDAP search filter used to search the LDAP directory for any matching users. In the filter %s will be replaced by the user name. If % is to be included literally in the filter then use %%

-g

Specifies that the first query argument sent to the helper by Squid is a extension to the basedn and will be temporarily added in front of the global basedn for this query.

-h ldapserver

Specify the LDAP server to connect to

-H ldapuri

Specify the LDAP server to connect to by a LDAP URI (requires OpenLDAP libraries)

-K

Strip Kerberos Realm component from user names (@ separated)

-p ldapport

Specify an alternate TCP port where the LDAP server is listening if other than the default LDAP port 389.

-P

Use a persistent LDAP connection. Normally the LDAP connection is only open while verifying a users group membership to preserve resources at the LDAP server. This option causes the LDAP connection to be kept open, allowing it to be reused for further user validations. Recommended for larger installations.

-R

Do not follow referrals

-s base|one|sub

search scope. Defaults to sub

base object only,

one level below the base object or

subtree below the base object

-S

Strip NT domain name component from user names (/ or \ separated)

-t search_timeout

Specify time limit on LDAP search operations

-u attr

LDAP attribute used to construct the user DN from the user name and base dn without needing to search for the user. A maximum of 16 occurrences of %s are supported.

-v 2|3

LDAP protocol version. Defaults to 3 if not specified.

-Z

Use TLS encryption

## CONFIGURATION
This helper is intended to be used as an external_acl_type helper in squid.conf .

external_acl_type ldap_group %LOGIN /path/to/ext_ldap_group_acl ...

acl group1 external ldap_group Group1

acl group2 external ldap_group Group2

NOTE: When constructing search filters it is recommended to first test the filter using ldapsearch to verify that the filter matches what you expect before you attempt to use ext_ldap_group_acl

## AUTHOR
This program was written by Flavio Pescuma <flavio@marasystems.com> Henrik Nordstrom <hno@squid-cache.org>

Based on prior work in squid_ldap_auth by Glen Newton <glen.newton@nrc.ca>

This manual was written by Henrik Nordstrom <hno@marasystems.com>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

Or contact your favorite LDAP list/friend if the question is more related to LDAP than Squid.

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), basic_ldap_auth(8), ldapsearch(1), GPL(7),

Your favorite LDAP documentation

RFC2254 - The String Representation of LDAP Search Filters,

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_session_acl(8)

text:
# ext_session_acl(8)

## NAME
ext_session_acl - Squid session tracking external acl helper.

Version 1.2

## SYNOPSIS
ext_session_acl [-t timeout ] [-b database ] [-a]

## DESCRIPTION
ext_session_acl maintains a concept of sessions by monitoring requests and timing out sessions. The timeout is based either on idle use ( -t ) or a fixed period of time ( -T ). The former is suitable for displaying terms and conditions to a user; the latter is suitable for the display of advertisements or other notices (both as a splash page - see config examples in the wiki online). The session helper can also be used to force users to re-authenticate if the %LOGIN and -a are both used.

## OPTIONS
-t timeout

Idle timeout for any session. The default if not specified (set to 3600 seconds).

-T timeout

Fixed timeout for any session. This will end the session after the timeout regardless of a user's activity. If used with active mode, this will terminate the user's session after timeout , after which another LOGIN will be required. LOGOUT will reset the session and timeout.

-b path

Path to persistent database. If a file is specified then that single file is used as the database. If a path is specified, a Berkeley DB database environment is created within the directory. The advantage of the latter is better database support between multiple instances of the session helper. Using multiple instances of the session helper with a single database file will cause synchronization problems between processes. If this option is not specified the session details will be kept in memory only and all sessions will reset each time Squid restarts its helpers (Squid restart or rotation of logs).

-a

Active mode. In this mode sessions are started by evaluating an acl with the argument LOGIN , or terminated by the argument LOGOUT . Without this flag the helper automatically starts the session after the first request.

## CONFIGURATION
The ext_session_acl helper is a concurrent helper; therefore, the concurrency= option must be specified in the configuration.

Passive session configuration example using the default automatic mode

external_acl_type session ttl=300 negative_ttl=0 children=1 concurrency=200 %LOGIN /usr/local/squid/libexec/ext_session_acl

acl session external session

http_access deny !session

deny_info http://your.server.example.com/bannerpage?url=%s session

Then set up http://your.server.example.com/bannerpage to display a session startup page and then redirect the user back to the requested URL given in the url query parameter.

## AUTHOR
This program and documentation was written by Henrik Nordstrom <henrik@henriknordstrom.net> Andrew Beverley <andy@andybev.com>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_time_quota_acl(8)

summary: Squid time quota external acl helper.

text:
# ext_time_quota_acl(8)

## NAME
ext_time_quota_acl - Squid time quota external acl helper.

Version 1.0

## SYNOPSIS
ext_time_quota_acl [-b database] [-d level] [-p pauselen] [-h] configfile

## DESCRIPTION
ext_time_quota_acl allows an administrator to define time budgets for the users of squid to limit the time using squid.

This is useful for corporate lunch time allocations, wifi portal pay-per-minute installations or for parental control of children. The administrator can define a time budget (e.g. 1 hour per day) which is enforced through this helper.

## OPTIONS
-b database

Filename of persistent database. This defaults to ext_time_quota.db in Squids state directory.

-p pauselen

Pauselen is given in seconds and defines the period between two requests to be treated as part of the same session. Pauses shorter than this value will be counted against the quota, longer ones ignored. Default is 300 seconds (5 minutes).

-d

Sets verbosity level for debugging section 82 (0-9; defaults to 1; see debug_options).

-h

show a short command line help.

configfile

This file contains the definition of the time budgets for the users.

## CONFIGURATION
The time quotas of the users are defined in a text file typically residing in /etc/squid/time_quota. Any line starting with "#" contains a comment and is ignored. Every line must start with a user followed by a time budget and a corresponding time period separated by "/". Here is an example file:

\# user budget / period

john 8h / 1d

littlejoe 1h / 1d

babymary 30m / 1w

John has a time budget of 8 hours every day, littlejoe is only allowed 1 hour and the poor babymary only 30 minutes a week.

You can use "s" for seconds, "m" for minutes, "h" for hours, "d" for days and "w" for weeks. Numerical values can be given as integer values or with a fraction. E.g. "0.5h" means 30 minutes.

This helper is configured in squid.conf using the external_acl_type directive then access controls which use it to allow or deny.

Here is an example.

\# Ensure that users have a valid login. We need their username.

acl users proxy_auth REQUIRED

http_access deny !users

\# Define program and quota file

external_acl_type time_quota ttl=60 children-max=1 %LOGIN /usr/libexec/ext_time_quota_acl /etc/squid/time_quota

acl noquota src all

acl time_quota external time_quota

deny_info ERR_ACL_TIME_QUOTA_EXCEEDED noquota

http_access deny !time_quota noquota

In this example, after restarting Squid it should allow access only for users as long as they have time budget left. If the budget is exceeded the user will be presented with an error page informing them.

In this example we use separate users access control and noquota ACL in order to keep the username and password prompt and the quota-exceeded messages separated.

User is just a unique key value. The above example uses %LOGIN and the username but any of the external_acl_type format tags can be substituted in its place. %EXT_TAG , %LOGIN , %EXT_USER , %SRC , %SRCEUI48 , and %SRCEUI64 are all likely candidates for client identification. The Squid wiki has more examples at https://wiki.squid-cache.org/ConfigExamples.

## LIMITATIONS
This helper only controls access to the Internet through HTTP. It does not control other protocols, like VOIP, ICQ, IRC, FTP, IMAP, SMTP or SSH.

Desktop browsers are typically able to deal with authentication to HTTP proxies like squid . But more and more different programs and devices (smartphones, games on mobile devices, ...) are using the Internet over HTTP. These devices are often not able to work through an authenticating proxy. Means other than %LOGIN authentication are required to authorize these devices and software.

A more general control to Internet access could be a captive portal approach (such as pfSense or ChilliSpot) using %SRC, %SRCEUI48 and %SRCEUI64 as keys or maybe a 802.11X solution. But the latter is often not supported by mobile devices.

## IMPLEMENTATION
When the helper is called it will be asked if the current user is allowed to access squid. The helper will reduce the remaining time budget of this user and return OK if there is budget left. Otherwise it will return ERR .

The ttl=N parameter in squid.conf determines how often the helper will be called, the example config uses a 1 minute TTL. The interaction is that Squid will only call the helper on new requests if there has been more than TTL seconds passed since last check. This handling creates an amount of slippage outside the quota by whatever amount is configured. TTL can be set as short as desired, down to and including zero. Though values of 1 or more are recommended due to a quota resolution of one second.

If the configured time period (e.g. "1w" for babymary) is over, the time budget will be restored to the configured value thus allowing the user to access squid with a fresh budget.

If the time between the current request and the previous request is greater than pauselen (default 5 minutes and adjustable with command line parameter -p ), the current request will be considered as a new request and the time budget will not be decreased. If the time is less than pauselen , then both requests will be considered as part of the same active time period and the time budget will be decreased by the time difference. This allows the user to take arbitrary breaks during Internet access without losing their time budget.

## FURTHER IDEAS
The following ideas could further improve this helper. Maybe someone wants to help? Any support or feedback is welcome!

There should be a way for a user to see their configured and remaining

time budget. This could be realized by implementing a web page accessing the database of the helper showing the corresponding data. One of the problems to be solved is user authentication.

We could always return "OK" and use the module simply as an Internet

usage tracker showing who has stayed how long in the WWW.

## AUTHOR
This program and documentation was written by Dr. Tilmann Bubeck <t.bubeck@reinform.de>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
squid(8), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_unix_group_acl(8)

summary: Squid UNIX Group ACL helper

text:
# ext_unix_group_acl(8)

## NAME
ext_unix_group_acl - Squid UNIX Group ACL helper

## SYNOPSIS
ext_unix_group_acl [-d] [-g group ] [-g group ...] [-p] [-s]

## DESCRIPTION
ext_unix_group_acl allows Squid to base access controls on users memberships in UNIX groups.

## OPTIONS
-d

Write debug info to stderr. -g group Specifies a group name to match.

-p

Also match the users primary group from /etc/passwd

-s

Strip NT domain name component from user names (/ or \ separated)

## CONFIGURATION
This squid.conf example defines two Squid acls. usergroup1 matches users in group1 , and usergroup2 matches users in group2 or group3

external_acl_type unix_group %LOGIN /usr/local/squid/libexec/ext_unix_group_acl -p

acl usergroup1 external unix_group group1

acl usergroup2 external unix_group group2 group3

By default up to 11 groups can be matched in one acl (including commandline specified groups). This limit is defined by MAX_GROUPS in the source code.

## KNOWN ISSUES
Does not understand GID aliased groups sometimes used to work around groups size limitations. If you are using GID aliased groups then you must specify each alias by name.

## AUTHOR
This program was written by Rodrigo Campos <rodrigo@geekbunker.org>

This manual was written by Henrik Nordstrom <hno@squid-cache.org>

## COPYRIGHT

* Copyright (C) 1996-2026 The Squid Software Foundation and contributors

*

* Squid software is distributed under GPLv2+ license and includes

* contributions from numerous individuals and organizations.

* Please see the COPYING and CONTRIBUTORS files for details.

This program and documentation is copyright to the authors named above.

Distributed under the GNU General Public License (GNU GPL) version 2 or later (GPLv2+).

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

Additionally bugs or bug-fixes can be reported to Rodrigo Campos <rodrigo@geekbunker.org>

## SEE ALSO
squid(8), group(5), passwd(5), GPL(7),

The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/


title: ext_wbinfo_group_acl(8)

text:
# ext_wbinfo_group_acl(8)

## NAME

```
 ext_wbinfo_group_acl - external ACL helper for Squid to verify NT Domain group membership using wbinfo.
```

## SYNOPSIS

```
 ext_wbinfo_group_acl [-dhK]
```

## DESCRIPTION
ext_wbinfo_group_acl is an installed executable script. It uses wbinfo from Samba to lookup group membership of logged in users.

This helper must be used in with an authentication scheme (typically Basic or NTLM) based on Windows NT/2000 domain users.

It reads from the standard input the domain username and a list of groups and tries to match each against the groups membership of the specified username.

## OPTIONS
-d

Write debug info to stderr.

-h

Print the help.

-K

Downgrade Kerberos credentials to NTLM.

## CONFIGURATION

```
  external_acl_type wbinfo_check %LOGIN /path/to/ext_wbinfo_group_acl
  acl allowed_group external wbinfo_check Group1 Group2
  http_access allow allowed_group
```

If the local perl interpreter is in a unusual location it may need to be added:

```
  external_acl_type wbinfo_check %LOGIN /path/to/perl /path/to/ext_wbinfo_group_acl
```

## AUTHOR
This program was written by Jerry Murdock <jmurdock@itraktech.com>

This manual was written by Amos Jeffries <amosjeffries@squid-cache.org>

## COPYRIGHT

```
 * Copyright (C) 1996-2026 The Squid Software Foundation and contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.
 This program is put in the public domain by Jerry Murdock
 <jmurdock@itraktech.com>. It is distributed in the hope that it will
 be useful, but WITHOUT ANY WARRANTY; without even the implied warranty
 of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
```

## QUESTIONS
Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

## REPORTING BUGS
Bug reports need to be made in English. See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

## SEE ALSO
The Squid FAQ wiki https://wiki.squid-cache.org/SquidFaq

The Squid Configuration Manual http://www.squid-cache.org/Doc/config/