SNIPROXY.CONF(5)

🎀 SNIPROXY.CONF(5) 🎀

okay bestie, welcome to the sniproxy config file zone — this is section 5 of the manual, and it's literally the whole vibe of how you tell sniproxy what to do. pull up a chair. 💅

---

✨ NAME ✨

sniproxy.conf — it's the configuration file for sniproxy. that's it, that's the name, she's simple and she knows it. 🦋

---

✨ SYNOPSIS ✨

/etc/sniproxy.conf

---

✨ DESCRIPTION ✨

so /etc/sniproxy.conf is the config file for sniproxy, no cap.

• Statements get separated by either a new line or a semi-colon. both. either. slay. 💫
• Lines that start with # are comments — your little diary entries, sniproxy will not read them.
• The whole config is broken down into stanzas, and those stanzas are delimited by curly braces.
• Characters may be escaped using \.
• Oh and here's a cute one: configuration directives may be shortened as long as they're unambiguous — e.g. user daemon instead of username daemon. iconic behaviour honestly. 👑

---

🌸 USERNAME 🌸

username daemon

Specify the user sniproxy will run as. When sniproxy is launched as super user, it will drop permissions down to this user. it's giving responsible. 🫶

---

🌸 PIDFILE 🌸

pidfile /var/run/sniproxy.pid

Specify the path to the pid file. heads up bestie: the directory must be writeable by the user sniproxy runs as. no write permission = no pid file = big sad. 😭

---

🌸 ERROR_LOG 🌸

error_log {
    syslog daemon
    priority notice
}

Specify how error messages should be handled. 😌

• Messages can be either logged to syslog — the syslog directive specifies that logs should go to a given syslog facility.
• Alternatively, the filename directive may be specified to log to a file.
• these two options are mutually exclusive — pick one, bestie, you cannot have both. 🚫
• The priority directive indicates what severity of messages should be logged.

Accepted priorities are the standard syslog priorities, listed here in increasing verbosity:

1. emergency
2. alert
3. critical
4. error
5. warning
6. notice
7. info
8. debug

---

🌸 ACCESS_LOG 🌸

access_log {
    filename /var/log/sniproxy/access.log
}

Specify how connections should be logged. this one can be overridden in a specific listener, so you can get per-listener main character energy. ✨

Connections are logged after both the client and server sockets have been closed — like, the whole conversation has to be over first. The syslog and priority directive may be used here just like in error_log. 💖

---

🌸 RESOLVER 🌸

resolver {
    nameserver 127.0.0.1
    mode ipv6_first
}

Specify how DNS queries should be resolved. ngl this is only required if you're using hostnames as addresses in the config, or using wildcard backends. If you don't specify it, IPv4-only queries will be performed using the system default name servers. casual. 🦋

Four modes are supported, and here they are:

• ipv4_only — query for any A records, use the first A record returned (following CNAME records).
• ipv6_only — query for any AAAA records, use the first AAAA record returned (following CNAME records).
• ipv4_first — query for both A and AAAA records, wait for both queries to complete, use the first A record if any, otherwise use the first AAAA record.
• ipv6_first — query for both A and AAAA records, wait for both queries to complete, use the first AAAA record if any, otherwise use the first A record.

⚠️ warning bestie, this one's serious. It is strongly recommended to use a local name server. why? because a single socket is reused for all DNS queries, so the UDP port number is predictable — meaning the query is only protected from spoofed replies by the 16 bit query ID. that's the whole protection. 🙈 Additionally, since no internal DNS caching is performed, a local resolver can improve performance. so like… local resolver. do it. 💜

---

🌸 LISTENER 🌸

listener 192.0.2.10:80 {
    protocol http
    reuseport yes
    table http_hosts
    fallback 192.0.2.100:80
    bad_requests log
    source 192.0.2.10

    access_log {
        filename /var/log/sniproxy/http_access.log
    }
}

listener [::]:80 {
    protocol http
    ipv6_v6only yes
    table http_hosts

    fallback unix:/var/run/http_fallback_unix.sock
}

Define a listening address to accept new connections from clients on. 🫶 Addresses may be specified as:

• an IPv4 literal followed by a TCP port number
• an IPv6 literal followed by a TCP port number
• a bare TCP port number
• a unix socket path prefixed with unix:

Protocol defines how the client request should be parsed to obtain the requested hostname. two protocols are supported: http and tls. 📡

Reuseport directive controls if the port is opened in SO_REUSEPORT mode, which allows one to run several sniproxy instances on the same ip:port pair. This enables us to evenly load-balance incoming connections between these instances without the use of any external load-balancing proxy. slay. 🔥 Requires Linux kernel 3.9+. Setting reuseport to "yes" enables this functionality.

The ipv6_v6only directive controls if listening on the IPv6 any address '::' will accept connections to any IPv4 address as well as an IPv6 address. This is useful if the user wants different configurations for IPv4 and IPv6, or wishes to handle IPv4 traffic with another server/proxy entirely. Only applicable to IPv6 listeners, and it's ignored on other listeners. 💅

Table specifies the name of the table used to lookup which server to forward the connection to, based on the hostname extracted from the initial client request. If no table directive is specified, the default, unnamed, table will be used.

The fallback directive specifies a server to be used if:

• the client request can not be parsed,
• a server can not be found in the table for the hostname specified, or
• the hostname can not be resolved.

This should be an IP address and port, or a unix socket path. 🍓

The bad_requests directive allows logging the contents of the client request if it is not parsable — super useful for debugging, fr fr. 🔍

The source directive allows specifying a specified address to bind to before connecting to the backend server. In most cases it is better to omit this option and allow the operating system to select the outgoing address automatically. Do not include a port number in this address — doing so will limit the proxy to one simultaneous connection to each server at a time. 😭

The access log configuration may be overridden on each listener. ✨

---

🌸 TABLE 🌸

table http_hosts {
    ^example\.com$ 192.0.2.101
    ^example\.net$ 192.0.2.102
    ^example\.org$ 192.0.2.103 proxy_protocol
}

Tables define how to map each hostname to a backend server. 🗺️ Each request's hostname is matched against entries in the table in order, until a match is found and that server is used.

The server address may be either:

• an IP
• an IP and port
• a unix socket path
• a hostname
• or '*'

If no port is specified, the port of the listener which the connection was received on will be used. 👑

The optional proxy_protocol option will prepend a HAProxy PROXY v1 protocol header to the proxied connection, allowing supporting webservers to obtain the source and destination IP and port of the original incoming TCP connection. it's giving ✨full context✨.

---

✨ SEE ALSO ✨

• sniproxy(8) — go read her too, bestie 💖

---

and that's the whole page!! you ate that. 💅✨ written by the SNIProxy manual, dated 22 March 2015 — yeah she's vintage but she's still iconic, and we love her for it. mwah. 🎀🦋💜