chilli.conf(5)

📦 version 1.7, in alpine 3.24

🌸 NAME 🌸

chilli.conf(5) — Chilli Configuration ✨ — yes, from the File Formats Manual.

💖 DESCRIPTION 💖

Okay so, bestie, chilli has so many configuration parameters, and you can use them either on the command line or in a configuration file. On the command line, options are prefixed with two dashes and may or may not have an equal sign. These are literally equivalent:

chilli --uamallowed www.example.com --uamanydns

chilli --uamallowed="www.example.com" --uamanydns

No-argument options are lowkey the same vibe — just no equal sign or second argument, periodt. In the configuration file, options must not have any dashes, but you can still use them with or without the equal sign, like this:

uamallowed www.example.com

uamallowed=www.example.com

uamanydns

And the hierarchy? Command-line options take precedent over anything defined in a configuration file — main character energy, fr fr. The default main config file is /etc/chilli.conf, and you can override it using the --conf option (or just --c for short) on the command line. Config files can also include other config files, like:

include /path/to/chilli/configfile.conf

Blank lines and comment lines starting with # are also allowed in the configuration file. Slay. 🎀

✨ OPTIONS ✨

Okay, vibe check: as mentioned above, all the options below can go on the command line (prefixed with --) or in a configuration file. A few options — shown below with the leading dashes — are typically only used on the command line. Not me listing every single one anyway 💅.

--help, -h — prints help and exits (command line).
--version, -V — prints version and exits (command line).
--fg, -f — runs server in foreground (command line).
--debug, -d — run server in debug mode (command line).
--debugfacility level — increase the debug level (command line) (should be named debuglevel).
--conf file, -c file — use the configuration file file instead of the default show in FILES (command line).
logfacility facility — the syslog(8) facility to use for logging. Highkey useful.
interval seconds — re-read configuration file and do DNS lookups every seconds. This has the same effect as sending the HUP signal. If seconds is 0 (zero), this feature is disabled.
pidfile file — filename to put the process id, see FILES for default.
statedir path — directory of non-volatile data, see FILES for default.
cmdsock file — UNIX socket used for communication with chilli_query(1), see FILES for default.
cmdsocketport port — UNIX port used for communication with chilli_query(1). Only used when cmdsocket is not defined. Default port is 42424.
net net — network address of the uplink interface (default = 192.168.182.0/24). The network address is set during initialisation when chilli establishes a tun device for the uplink interface. The network address is specified as either <address>/<netmask> (192.168.182.0/255.255.255.0) or <address>/<prefix> (192.168.182.0/24).
dynip net — dynamic IP address pool. Specifies a pool of dynamic IP addresses. If this option is omitted the network address specified by the net option is used for dynamic IP address allocation. See the net option for a description of the network address format.
statip net — static IP address pool. Specifies a pool of static IP addresses. With static address allocation the IP address of the client can be specified by the radius server. Static address allocation can be used for both MAC authentication and Wireless Protected Access.
dhcpgateway ipaddress — IP address of a DHCP server (on the uplink network). If configured DHCP requests will be relayed to this server.
dhcpgatewayport port — port number to use when relaying requests to the DHCP server configured via dhcpgateway at. Defaults to 67.
dhcprelayagent ipaddress — IP address to use when relaying DHCP requests to the DHCP gateway.
dns1 host — DNS Server 1. It is used to inform the client about the DNS address to use for host name resolution. If this option is not given the system primary DNS is used.
dns2 host — DNS Server 2. It is used to inform the client about the DNS address to use for host name resolution. If this option is not given the system secondary DNS is used.
domain domain — domain name. It is used to inform the client about the domain name to use for DNS lookups.
ipup script — script executed after the TUN/TAP network interface has been brought up. Executed with the following parameters: <device-name> <ip-address> <net-mask> and with environment variables:
- DEV=<tun/tap-device-name> — the TUN/TAP device being brought up.
- ADDR=<tun/tap-device-ip> — the TUN/TAP device IP address being brought up.
- MASK=<tun/tap-device-mask> — the TUN/TAP device net mask being brought up.
- NET=<tun/tap-device-net> — the TUN/TAP device network being brought up.
- DHCPIF=<interface> — the dhcpif configured in chilli.conf(5).
- UAMPORT=<port-num> — the uamport configured in chilli.conf(5).
- UAMUIPORT=<port-num> — the uamuiport configured in chilli.conf(5).
ipdown script — script executed after the tun network interface has been taken down with the same arguments and environment variables as above.
conup script — script executed after a session is authorized. Executed with the following environment variables (see source code for possibly more):
- DEV=<tun/tap-device> — the TUN/TAP device.
- ADDR=<chilli-ip> — IP Address of chilli, see the uamlisten option.
- NET=<chilli-net> — network of chilli, see the net option.
- MASK=<chilli-net-mask> — network mask of chilli, see the net options.
- NAS_IP_ADDRESS=<radiuslisten> — is set to the radiuslisten value.
- NAS_ID=<nas-id> — the radiusnasid option.
- WISPR_LOCATION_ID=<location-id> — the radiuslocationid option.
- WISPR_LOCATION_NAME=<location-name> — the radiuslocationname option.
- USER_NAME=<username> — user-name used to login.
- FRAMED_IP_ADDRESS=<client-ip> — the client's IP Address.
- CALLING_STATION_ID=<client-mac> — the client's MAC Address.
- CALLED_STATION_ID=<chilli-mac> — the MAC address of the chilli interface.
- FILTER_ID=<filter> — a possible filter ID returned in RADIUS Filter-ID.
- SESSION_TIMEOUT=<seconds> — the max session time, as set by RADIUS Session-Timeout.
- IDLE_TIMEOUT=<seconds> — the max idle time, as set by RADIUS Idle-Timeout.
- WISPR_BANDWIDTH_MAX_UP=<bandwidth> — max up stream bandwidth set by RADIUS WISPr-Bandwidth-Max-Up.
- WISPR_BANDWIDTH_MAX_DOWN=<bandwidth> — max down stream bandwidth set by RADIUS WISPr-Bandwidth-Max-Down.
- COOVACHILLI_MAX_INPUT_OCTETS=<bytes> — max input octets set by RADIUS CoovaChilli-Max-Input-Octets.
- COOVACHILLI_MAX_OUTPUT_OCTETS=<bytes> — max output octets set by RADIUS CoovaChilli-Max-Output-Octets.
- COOVACHILLI_MAX_TOTAL_OCTETS=<bytes> — max total octets set by RADIUS CoovaChilli-Max-Total-Octets.
condown script — script executed after a session has moved from authorized state to unauthorized with the same environment variables as above.
ssid ssid — a parameter that is passed on to the UAM server in the initial redirect URL.
vlan vlan — a parameter that is passed on to the UAM server in the initial redirect URL.
nasip ipaddress — value to use in RADIUS NAS-IP-Address attribute. If not present, radiuslisten is used (which defaults to "0.0.0.0").
nasmac mac — MAC address value to use in RADIUS Called-Station-ID attribute. If not present, the MAC address of the dhcpif is used for Called-Station-ID.
radiuslisten host — local interface IP address to use for the radius interface. Defaults to the value used in RADIUS NAS-IP-Address when nasip is not set.
radiusserver1 host — the IP address of radius server 1 (default=rad01.coova.org).
radiusserver2 host — the IP address of radius server 2 (default=rad01.coova.org).
radiusauthport port — the UDP port number to use for radius authentication requests (default 1812).
radiusacctport port — the UDP port number to use for radius accounting requests (default 1813).
radiussecret secret — Radius shared secret for both servers (default coova-anonymous). This secret should be changed in order not to compromise security. 🚨
radiusnasid id — network access server identifier (default nas01).
radiuslocationid id — WISPr Location ID. Should be in the format: isocc=<ISO_Country_Code>, cc=<E.164_Country_Code>, ac=<E.164_Area_Code>, network=<ssid/ZONE>. This parameter is further described in the document: Wi-Fi Alliance - Wireless ISP Roaming - Best Current Practices v1, Feb 2003.
radiuslocationname name — WISPr Location Name. Should be in the format: <HOTSPOT_OPERATOR_NAME>,<LOCATION>. This parameter is further described in the document: Wi-Fi Alliance - Wireless ISP Roaming - Best Current Practices v1, Feb 2003.
radiusnasporttype type — value of NAS-Port-Type attribute. Defaults to 19 (Wireless-IEEE-802.11).
radiusoriginalurl — flag (defaults to off) to send the CoovaChilli-OriginalURL RADIUS VSA in Access-Request.
adminuser username — user-name to use for Administrative-User authentication in order to pick up chilli configurations and establish a device 'system' session.
adminpasswd password — password to use for Administrative-User authentication in order to pick up chilli configurations and establish a device 'system' session.
adminupdatefile filename — okay so this is the file you use as the Administrative-User update file, bestie. When you pair it with the adminuser and adminpasswd options above, any CoovaChilli-Config RADIUS attributes found in the Administrative-User Access-Accept get put into the file you specify. If the file changes, chilli will reload its configuration (it’s assumed this file is included into the chilli configuration file). 💅
swapoctets — swaps the meaning of “input octets” and “output octets” as it relates to RADIUS attributes. 🔄
openidauth — lets OpenID authentication happen by sending CoovaChilli-Config=allow-openidauth in RADIUS Access-Requests, so the RADIUS server knows about the option. ✨
wpaguests — lets WPA Guest authentication happen by sending CoovaChilli-Config=allow-wpa-guests in RADIUS Access-Requests, so the RADIUS server knows about the option. The RADIUS may come back with an Access-Accept containing CoovaChilli-Config=require-uam-auth to give WPA access, but still enforce the captive portal. 🫶
coaport port — the UDP port to listen to for accepting radius disconnect requests. 👑
coanoipcheck — if this option is given, no check is performed on the source IP address of radius disconnect requests. Otherwise, it is checked that radius disconnect requests originate from radiusserver1 or radiusserver2. 🔍
proxylisten host — local interface IP address to use for accepting radius requests. 📡
proxyport port — UDP port to listen to for accepting radius requests. 🔌
proxyclient host — IP address from which radius requests are accepted. If omitted, the server will not accept radius requests. 🙅‍♀️
proxysecret secret — radius shared secret for clients. If not specified, it defaults to radiussecret. 🤫
dhcpif dev — Ethernet interface to listen to for the downlink interface. This option must be specified. 🚨
usetap — use the TAP interface instead of TUN (Linux only). 🐧
noarpentries — do not create arp table entries when using TAP. (Linux only). 🐧
nexthop mac-address — specify a MAC address which is the layer 2 next hop to route packets to (used with usetap only). 🧭
rtmonfile file — option to launch the chilli_rtmon daemon with the specified file as the update file. The chilli_rtmon daemon will update the file with a nexthop configuration entry before sending chilli a SIGHUP to reread its configuration. 🔁
tcpwin number — specify an integer value for the TCP Window and TCP Maximum Segment Size. If set, packets are rewritten with the values for both Window and MSS. 📦
tundev dev — the specific device to use for the TUN/TAP interface. 🎛️
txqlen bytes — the TX queue length to set on the TUN/TAP interface. 📏
dhcpmac address — MAC address to listen to. If not specified, the MAC address of the interface will be used. The MAC address should be chosen so that it does not conflict with other addresses on the LAN. An address in the range 00:00:5E:00:02:00 - 00:00:5E:FF:FF:FF falls within the IANA range of addresses and is not allocated for other purposes. The dhcpmac option can be used in conjunction with access filters in the access points, or with access points which supports packet forwarding to a specific MAC address. Thus it is possible at the MAC level to separate access point management traffic from user traffic for improved system security. The dhcpmac option will set the interface in promisc mode. 💳
lease seconds — use a DHCP lease of seconds (default 600). ⏳
dhcpstart number — where to start assigning IP addresses (default 10). 🔢
dhcpend number — where to stop assigning IP addresses (default 254). 🔢
dhcpbroadcast — always respond to DHCP to the broadcast IP, when no relay. 📢
eapolenable — if this option is given, IEEE 802.1x authentication is enabled. CoovaChilli will listen for EAP authentication requests on the interface specified by dhcpif. EAP messages received on this interface are forwarded to the radius server. 🔐
ieee8021q — option to enable support for 802.1Q/VLAN network on the dhcpif interface. 🏷️
uamserver url — URL of web server to use for authenticating clients. 🌐
uamhomepage url — URL of homepage to redirect unauthenticated users to. If not specified, this defaults to uamserver. 🏠
uamaaaurl url — when chilli is built with the --enable-chilliproxy compile-time option, this configuration option can be used to define a URL to use for the HTTP AAA protocol described here: http://www.coova.org/CoovaChilli/Proxy. 🧾
wisprlogin url — a specific URL to be given in WISPr XML LoginURL. Otherwise, uamserver is used. 🎫
uamsecret secret — shared secret between uamserver and chilli. This secret should be set in order not to compromise security. 🔒
uamlisten host — IP address to listen to for authentication of clients. If an unauthenticated client tries to access the Internet, they will be redirected to this address. 🛣️
uamport port — TCP port to bind to for authenticating clients (default = 3990). If an unauthenticated client tries to access the Internet, they will be redirected to this port on the uamlisten IP address. 🚪
uamuiport port — TCP port to bind to for only serving embedded content. 🖼️
uamallowed domain — comma separated list of resources the client can access without first authenticating. Each entry in the list can be a domain name, IP address, or network segment. Example: uamallowed www.example.com,10.11.12.0/24. Where each entry can be made more specific by specifying a protocol and port in the format host/network:port or protocol:host/network or protocol:host/network:port, where protocol is a protocol name from /etc/protocols, host/network is just as above (a domain, IP, or network), and port is a port number. Example: uamallowed www.example.com:80,icmp:www.example.com. Adding to your walled garden is useful for allowing access to credit card payment gateways, community website, or other publicly available resources. CoovaChilli resolves the domain names to a set of IP addresses during startup. Some big sites change the returned IP addresses for each lookup. This behaviour is not compatible with this option. Domain names in the list do get updated periodically based on the interval option. It is possible to specify the uamallowed option several times. This is useful if many domain names have to be specified. 🌺
uamdomain domain — one domain prefix per use of the option; defines a list of domain names to automatically add to the walled garden. This is done by the inspecting of DNS packets being sent back to the subscriber. 🕵️‍♀️
uamregex host-pattern::path-pattern::qs-pattern — when chilli is built with the --enable-chilliredir option given to the configure script, the uamregex option is available. The value should be a :: separated list of three values; the regex patterns to match the Host header, the URL path, and the query string of the request. The patterns follow the regex(7) syntax with the addition of * meaning anything (or to not check that field) and any pattern starting with ! will be negated in meaning. Example: --uamregex='.google.com$::!^mail/::*'. This will allow all requests to a .google.com host except if the URL starts with mail (links to Gmail). 🧚
defsessiontimeout seconds — default session timeout (max session time) unless otherwise set by RADIUS (defaults to 0, meaning unlimited). ⏱️
defidletimeout seconds — default idle timeout (max idle time) unless otherwise set by RADIUS (defaults to 0, meaning unlimited). 😴
definteriminterval seconds — default interim-interval for RADIUS accounting unless otherwise set by RADIUS (defaults to 0, meaning unlimited). 📊
defbandwidthmaxdown — default bandwidth max down set in bps, same as WISPr-Bandwidth-Max-Down. ⬇️
defbandwidthmaxup — default bandwidth max up set in bps, same as WISPr-Bandwidth-Max-Up. ⬆️
acctupdate — allow updating of session parameters with RADIUS attributes sent in Accounting-Response. 🔄
wwwdir path — directory where embedded local web content is placed. This content is accessible using the URL format http://<uamlisten>:<uamport>/www/<filename>. 📁
wwwbin script — executable to run as a CGI type program (like haserl) for URLs with extention .chi - in the format http://<uamlisten>:<uamport>/www/<file>.chi. 🛠️
uamui script — an init.d style program to handle local content on the uamuiport web server. 🧩
uamanydns — allow any DNS server. Normally unauthenticated clients are only allowed to communicate with the DNS servers specified by the dns1 and dns2 options. If the uamanydns option is given, CoovaChilli will allow the client to use all DNS servers. This is convenient for clients which are configured to use a fixed set of DNS servers. Since the server may not be available, requests are forwarded to the dns1 server. 🌈
uamlogoutip ipaddress — use this IP address to instantly logout a client accessing it (defaults to 1.0.0.0). 🚪
uamaliasip ipaddress — a special IP address that will always get hijacked to the UAM server (either to the uamuiport, if defined, otherwise uamport; defaults to 1.0.0.1). 🪄
uamaliasname name — an (unqualified, so no dots) hostname that is used as a DNS alias for the uamaliasip defined above. Any DNS request for this hostname, or this hostname under the domain will be returned with the uamaliasip IP address. 🏷️
dnsparanoia — inspect DNS packets and drop responses with any non-A, CNAME, SOA, or MX records (to prevent dns tunnels; experimental). 🚨
domaindnslocal — option to have chilli return the uamaliasip for all DNS requests for a hostname under the domain that is configured. 🏡
uamanyip — allow clients to use any IP settings they wish by spoofing ARP (experimental). 🧪
nouamsuccess — no bouncing back to the UAM server after a successful login</p>, bestie; just redirect to the original URL. 💅
nouamwispr — skip WISPr XML completely and assume the back-end is handling it instead. No cap.
usestatusfile — write the status of clients into a non-volatile state file. (experimental — literally flagged experimental, so vibe-check before relying on it.)
chillixml — return the so-called Chilli XML along with WISPr XML. ✨
macauth — if this option is given, CoovaChilli tries to authenticate all users based on their MAC address alone. The User-Name sent to the RADIUS server consists of the MAC address plus an optional suffix specified by the macsuffix option. If macauth is specified, macallowed is ignored. 💅
macallowed mac — list of MAC addresses for which MAC authentication will be performed. Example:

macallowed 00-0A-5E-AC-BE-51,00-30-1B-3C-32-E9

The User-Name sent to the RADIUS server consists of the MAC address plus an optional suffix specified by the macsuffix option. If macauth is specified, macallowed is ignored. You can specify macallowed several times — useful when lots of MAC addresses have to be specified. 🫶

macsuffix suffix — suffix to add to the MAC address to form the User-Name that gets sent to the RADIUS server.
macpasswd password — password used when performing MAC authentication. Default is password.
macallowlocal — allow MAC authentication based on macallowed without using RADIUS authentication.
ethers file — a file containing MAC address and IP address mappings for DHCP allocation. It should be formatted as:

00-XX-XX-XX-XX-XX  IP.IP.IP.IP

localusers file — a colon-separated file containing usernames and passwords of locally authenticated users.
postauthproxy ipaddress — used together with postauthproxyport to define a post-authentication HTTP proxy server.
postauthproxyport port — used together with postauthproxy to define a post-authentication HTTP proxy server.
locationname name — human-readable location name used in the JSON interface.
papalwaysok — (now deprecated; always on) was used to allow PAP authentication. It’s always on now, bestie — no switch to flip.

🔐 SSL OPTIONS 🔐

The following options are available when chilli is built with SSL support. Slay, but only if you compiled it that way. 💅

sslkeyfile filename — defines the location of the PEM-formatted private key file.
sslkeypass password — the password, if any, that protects the private key.
sslcertfile filename — defines the location of the PEM-formatted certificate file.
sslcafile filename — defines the location of the PEM-formatted CA certificate file.
sslciphers ciphers — defines the ciphers that will be used.
redirssl — when set, HTTPS requests by unauthorized clients get hijacked instead of dropped. Requires at least sslkeyfile and sslcertfile to be defined. Hijacked, not dropped — noted.
uamuissl — when set, uamuiport is enabled with SSL. Requires at least sslkeyfile and sslcertfile to be defined.
radsec — when set, a RadSec RADIUS tunnel is established. Requires at least sslkeyfile, sslcertfile, and sslcafile to be defined.

📁 FILES 📁

/etc/chilli.conf — the main chilli configuration file. By default, this file includes three other files: main.conf, hs.conf, and local.conf. The main.conf and hs.conf files are created by the shell script routines in functions based on configurations in the files mentioned below, and can possibly take some configurations from a remote RADIUS server or URL. The local.conf file is reserved for location-specific configurations. 🎀
/etc/chilli/defaults — default configurations used by the chilli init.d and functions scripts when creating the actual configuration files. See the comments in this file for more information on how to configure chilli and related scripts and embedded content.
/etc/chilli/config — location-specific configurations used by the chilli init.d and functions scripts. Copy the defaults file mentioned above and edit it. This file is loaded after the defaults and thus will override settings.
/etc/chilli/functions — helps configure chilli by loading the above configurations, sets some defaults, and provides functions for writing main.conf, hs.conf, and local.conf based on local and possibly centralized settings.
/etc/init.d/chilli — the init.d file for chilli, which defaults to using the above configurations to build a set of configuration files in the /etc/chilli directory — taking local configurations and optionally centralized configurations from RADIUS or a URL. 🔥

👀 SEE ALSO 👀

📝 NOTES 📝

See http://coova.github.io/ for further documentation and community support. ✨

👑 AUTHORS 👑

David Bird — <david@coova.com>

CoovaChilli is licensed under the GNU General Public License.

Okay that’s the whole thing, bestie — source/version chilli.conf(5), dated August 2007 🫶✨

📦 where this page comes from

alpine 3.24: coova-chilli-doc 1.7-r0 · GPL-3.0-or-later
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash-1017 on 2026-11-04: a language model's rewrite of the original, under its terms