dnsmasq manpage

Navigation
computing: software: dnsmasq: manpage

NAME
dnsmasq - A lightweight DHCP and caching DNS server.

SYNOPSIS
dnsmasq [OPTION]...

DESCRIPTION
dnsmasq is  a lightweight DNS, TFTP and DHCP server. It is intended to provide coupled DNS and DHCP service to a LAN.

Dnsmasq accepts DNS queries and either answers them from a small, local, cache or forwards them to  a  real, recursive, DNS server. It loads the contents of /etc/hosts so that local hostnames which do not appear in the global DNS can  be  resolved  and  also  answers  DNS queries for DHCP configured hosts.

The dnsmasq DHCP server supports static address assignments, multiple networks, DHCP-relay and RFC3011 subnet specifiers. It automatically sends  a  sensible  default  set  of  DHCP options, and  can be configured to send any desired set of DHCP options, including vendor- encapsulated options. It includes a secure, read-only, TFTP server to allow net/PXE boot of      DHCP hosts and also supports BOOTP.

Dnsmasq supports IPv6 for DNS, but not DHCP.

OPTIONS
A summary of these options (as returned by "dnsmasq --help") is in dnsmasq options.

Note that in general missing parameters are allowed and switch off functions, for instance "--pid-file" disables writing a PID file. On BSD, unless the GNU getopt library is linked, the long  form of the options does not work on the command line; it is still recognised in       the configuration file.

-h, --no-hosts Don’t read the hostnames in /etc/hosts.

-H, --addn-hosts= Additional hosts file. Read the specified file as well  as  /etc/hosts. If -h  is              given,  read  only the specified file. This option may be repeated for more than one additional hosts file.

-E, --expand-hosts Add the domain to simple names (without a period) in /etc/hosts in the same way  as              for DHCP-derived names.

-T, --local-ttl= When replying  with  information from /etc/hosts or the DHCP leases file dnsmasq by              default sets the time-to-live field to zero, meaning that the requestor  should  not itself cache  the information. This is the correct thing to do in almost all situa‐ tions. This option allows a time-to-live (in seconds) to be given for these replies. This will  reduce the load on the server at the expense of clients using stale data under some circumstances.

-k, --keep-in-foreground Do not go into the background at startup but  otherwise  run  as  normal. This is              intended for use when dnsmasq is run under daemontools or launchd.

-d, --no-daemon Debug mode: don’t fork to the background, don’t write a pid file, don’t change user id, generate a complete cache dump on receipt on SIGUSR1, log to stderr as well  as              syslog, don’t fork new processes to handle TCP queries.

-q, --log-queries Log the  results  of  DNS  queries  handled by dnsmasq. Enable a full cache dump on             receipt of SIGUSR1.

-8, --log-facility= Set the facility to which dnsmasq will send syslog entries, this defaults to DAEMON, and to  LOCAL0  when  debug  mode is in operation. If the facilty given contains at             least one ’/’ character, it is taken to be a filename, and dnsmasq logs to the given file, instead of syslog. (Errors whilst reading configuration will still go to sys‐             log, but all output from a successful startup, and all output whilst  running,  will              go exclusively to the file.)

--log-async[= ] Enable asynchronous  logging  and  optionally  set the limit on the number of lines which will be queued by dnsmasq when writing to the syslog is slow. Dnsmasq can log asynchronously: this allows it to continue functioning without being blocked by sys‐ log, and allows syslog to use dnsmasq for DNS queries without risking deadlock. If             the  queue  of log-lines becomes full, dnsmasq will log the overflow, and the number of messages lost. The default queue length is 5, a sane value would be 5-25, and a              maximum limit of 100 is imposed.

-x, --pid-file= Specify an  alternate  path  for  dnsmasq  to  record  its  process-id in. Normally /var/run/dnsmasq.pid.

-u, --user= Specify the userid to which dnsmasq will change after startup. Dnsmasq must normally be started as root, but it will drop root privileges after startup by changing id to             another user. Normally this user is "nobody" but that can be over-ridden with  this switch.

-g, --group= Specify the group which dnsmasq will run as. The defaults to "dip", if available, to             facilitate access to /etc/ppp/resolv.conf which is not normally world readable.

-v, --version Print the version number.

-p, --port= Listen on instead of the standard DNS port (53). Useful mainly for debugging.

-P, --edns-packet-max= Specify the  largest  EDNS.0  UDP  packet  which is supported by the DNS forwarder. Defaults to 1280, which is the RFC2671-recommended maximum for ethernet.

-Q, --query-port= Send outbound DNS queries from, and listen for their replies on, the  specific  UDP port   instead of using one chosen at runtime. Useful to simplify your firewall rules; without this, your firewall would have to  allow  connections  from outside DNS servers to a range of UDP ports, or dynamically adapt to the port being used by the current dnsmasq instance.

-i, --interface= Listen only on the specified interface(s). Dnsmasq automatically adds the  loopback (local) interface  to the list of interfaces to use when the --interface option  is              used. If no --interface or --listen-address options are given dnsmasq listens on all available interfaces except any given in --except-interface options. IP alias inter‐ faces (eg "eth1:0") cannot be used with --interface or --except-interface  options, use --listen-address instead.

-I, --except-interface= Do not  listen  on the specified interface. Note that the order of --listen-address --interface and --except-interface options does not matter and that --except-inter‐ face options always override the others.

-2, --no-dhcp-interface= Do not provide DHCP or TFTP on the specified interface, but do provide DNS service.

-a, --listen-address= Listen on the given IP address(es). Both --interface and  --listen-address  options may be  given, in which case the set of both interfaces and addresses is used. Note that if no --interface option is given, but --listen-address is, dnsmasq  will  not automatically listen  on  the  loopback interface. To achieve this, its IP address, 127.0.0.1, must be explicitly given as a --listen-address option.

-z, --bind-interfaces On systems which support it, dnsmasq binds the wildcard address, even  when  it  is              listening on only some interfaces. It then discards requests that it shouldn’t reply to. This has the advantage of working even when interfaces come and go  and  change address. This option forces dnsmasq to really bind only the interfaces it is listen‐ ing on. About the only time when this is useful is when running another  nameserver (or another  instance  of  dnsmasq)  on  the same machine. Setting this option also enables multiple instances of dnsmasq which provide DHCP service to run in the same machine.

-y, --localise-queries Return answers  to  DNS  queries from /etc/hosts which depend on the interface over which the query was received. If a name in /etc/hosts has  more  than  one  address associated with it, and at least one of those addresses is on the same subnet as the interface to which the query was sent, then return only the address(es) on that sub‐ net. This allows for a server to have multiple addresses in /etc/hosts correspond‐ ing to each of its interfaces, and hosts will get the correct address based on which network they are attached to. Currently this facility is limited to IPv4.

-b, --bogus-priv Bogus private  reverse  lookups. All reverse  lookups  for  private IP ranges (ie              192.168.x.x, etc) which are not found in /etc/hosts or  the  DHCP  leases  file  are answered with "no such domain" rather than being forwarded upstream.

-V, --alias=,[, ] Modify IPv4 addresses returned from upstream nameservers; old-ip is replaced by new- ip. If the optional mask is given then any address which matches the masked  old-ip will be re-written. So, for instance --alias=1.2.3.0,6.7.8.0,255.255.255.0 will map 1.2.3.56 to 6.7.8.56 and 1.2.3.67 to 6.7.8.67. This is what Cisco PIX routers  call "DNS doctoring".

-B, --bogus-nxdomain= Transform replies which contain the IP address given into "No such domain" replies. This is intended to counteract a devious move made by Verisign  in  September  2003 when they  started  returning the address of an advertising web page in response to              queries for unregistered names, instead  of  the  correct  NXDOMAIN  response. This option tells dnsmasq to fake the correct response when it sees this behaviour. As at             Sept 2003 the IP address being returned by Verisign is 64.94.110.11

-f, --filterwin2k Later versions of windows make periodic  DNS  requests  which  don’t  get  sensible answers from  the  public  DNS  and can cause problems by triggering dial-on-demand links. This flag turns on an option to filter such requests. The requests  blocked are for  records  of  types  SOA and SRV, and type ANY where the requested name has underscores, to catch LDAP requests.

-r, --resolv-file= Read the  IP  addresses  of  the  upstream  nameservers  from ,  instead  of              /etc/resolv.conf. For the format of this file see resolv.conf(5); the only lines rel‐ evant to dnsmasq are nameserver ones. Dnsmasq can be told to  poll  more  than  one resolv.conf file,  the first file name  specified overrides the default, subsequent ones add to the list. This is only allowed when polling; the file with the currently latest modification time is the one used.

-R, --no-resolv Don’t read /etc/resolv.conf. Get upstream servers only from the command line or the dnsmasq configuration file.

-1, --enable-dbus Allow dnsmasq configuration to be updated via DBus method calls. The configuration which can  be changed is upstream DNS servers (and corresponding domains) and cache clear. Requires that dnsmasq has been built with DBus support.

-o, --strict-order By default, dnsmasq will send queries to any of the upstream servers it knows about and tries to favour servers to are known to be up. Setting this flag forces dnsmasq to try  each  query  with  each  server  strictly  in  the  order  they  appear  in              /etc/resolv.conf

-n, --no-poll Don’t poll /etc/resolv.conf for changes.

--clear-on-reload Whenever /etc/resolv.conf is re-read, clear the DNS cache. This is useful when new nameservers may have different data than that held in cache.

-D, --domain-needed Tells dnsmasq to never forward queries for plain  names,  without  dots  or  domain parts, to  upstream  nameservers. If the name is not known from /etc/hosts or DHCP then a "not found" answer is returned.

-S, --local, --server=[/[ ]/[domain/]][ [# ][@ [# ]]] Specify IP address of upstream severs directly. Setting this flag does not suppress reading of /etc/resolv.conf, use -R to do that. If one or more optional domains are given, that server is used only for those domains and they are queried  only  using the specified server. This is intended for private nameservers: if you have a name‐ server on your network which deals with  names  of  the  form  xxx.internal.thekel‐ leys.org.uk  at   192.168.1.1   then   giving    the   flag   -S  /internal.thekel‐ leys.org.uk/192.168.1.1 will send all queries for internal machines to  that  name‐ server, everything else will go to the servers in /etc/resolv.conf. An empty domain specification, // has the special meaning of "unqualified names only" ie names with‐ out any dots in them. A non-standard port may be specified as part of the IP address using a # character. More than one -S flag is allowed,  with  repeated  domain  or              ipaddr parts as required.

Also permitted is a -S flag which gives a domain but no IP address; this tells dns‐ masq that a domain is local and it may answer queries from /etc/hosts or  DHCP  but should never  forward  queries  on that domain to any upstream servers. local is a             synonym for server to make configuration files clearer in this case.

The optional second IP address after the @ character tells dnsmasq how to  set  the source address of the queries to this nameserver. It should be an address belonging to the machine on which dnsmasq is running otherwise this server line will be logged and then ignored. The query-port flag is ignored for any servers which have a source address specified but the port may be specified directly  as  part  of  the  source address.

-A, --address=/ /[domain/] Specify an  IP address to return for any host in the given domains. Queries in the domains are never forwarded and always replied to with  the  specified  IP  address which may  be  IPv4 or IPv6. To give both IPv4 and IPv6 addresses for a domain, use repeated -A flags. Note that /etc/hosts and DHCP leases override this for individ‐ ual names. A common use of this is to redirect the entire doubleclick.net domain to             some friendly local web server to avoid banner ads. The domain specification  works in the  same was as for --server, with the additional facility that /#/ matches any domain. Thus --address=/#/1.2.3.4 will always return  1.2.3.4  for  any  query  not answered from  /etc/hosts  or DHCP and not sent to an upstream nameserver by a more specific --server directive.

-m, --mx-host= [[, ], ]             Return an MX record named pointing to the given hostname  (if  given),  or              the  host  specified  in the --mx-target switch or, if that switch is not given, the              host on which dnsmasq is running. The default is useful for directing mail from sys‐              tems on a LAN to a central server. The preference value is optional, and defaults to              1 if not given. More than one MX record may be given for a host.

-t, --mx-target= Specify the default target for the MX record returned by dnsmasq. See --mx-host. If             --mx-target is given, but not --mx-host, then dnsmasq returns a MX record containing the MX target for MX queries on the hostname of the machine  on  which  dnsmasq  is              running.

-e, --selfmx Return an  MX  record pointing to itself for each local machine. Local machines are those in /etc/hosts or with DHCP leases.

-L, --localmx Return an MX record pointing to the host given by mx-target (or the machine on which             dnsmasq  is  running) for each local machine. Local machines are those in /etc/hosts or with DHCP leases.

-W, --srv-host=&lt;_service&gt;.&lt;_prot&gt;.[&lt;domain&gt;],[&lt;target&gt;[,&lt;port&gt;[,&lt;priority&gt;[,&lt;weight&gt;]]]] Return a SRV DNS record. See RFC2782 for  details. If not  supplied,  the  domain defaults to that given by --domain. The default for the target domain is empty, and the default for port is one and the defaults for weight and priority are  zero. Be             careful if transposing data from BIND zone files: the port, weight and priority num‐ bers are in a different order. More than one SRV record for a given  service/domain is allowed, all that match are returned.

-Y, --txt-record=&lt;name&gt;[[,&lt;text&gt;],&lt;text&gt;]             Return a TXT DNS record. The value of TXT record is a set of strings, so  any number              may be included, split by commas.

--ptr-record=&lt;name&gt;[,&lt;target&gt;] Return a PTR DNS record.

--interface-name=&lt;name&gt;,&lt;interface&gt; Return a DNS record associating the name with the  primary  address  on  the  given interface. This flag specifies an A record for the given name in the same way as an             /etc/hosts line, except that the address is not constant, but taken from  the  given interface. If the interface is down, not configured or non-existant, an empty record is returned. The matching PTR record is also created, mapping the interface address to the  name. More than  one  name may be associated with an interface address by              repeating the flag; in that case the first instance is used for the reverse address- to-name mapping.

-c, --cache-size= Set the size of dnsmasq’s cache. The default is 150 names. Setting the cache size to             zero disables caching.

-N, --no-negcache Disable negative caching. Negative caching allows  dnsmasq  to  remember  "no  such              domain"  answers from upstream nameservers and answer identical queries without for‐ warding them again. This flag disables negative caching.

-0, --dns-forward-max= Set the maximum number of concurrent DNS queries. The default value is  150,  which should be  fine  for  most  setups. The only known situation where this needs to be             increased is when using web-server log file resolvers, which can generate large num‐ bers of concurrent queries.

-F,           --dhcp-range=[[net:]network-id,],[[, ],][, ]              Enable  the  DHCP server. Addresses will be given out from the range  to               and from statically defined addresses given in dhcp-host options. If  the              lease  time  is  given, then leases will be given for that length of time. The lease              time is in seconds, or minutes (eg 45m) or hours (eg 1h) or the literal  "infinite".              This  option  may  be  repeated, with different addresses, to enable DHCP service to              more than one network. For directly connected networks (ie, networks  on  which  the              machine  running  dnsmasq has an interface) the netmask is optional. It is, however,              required for networks which receive DHCP service via a relay  agent.  The  broadcast              address  is  always optional. On some broken systems, dnsmasq can listen on only one              interface when using DHCP, and the name of that interface must be  given  using  the              interface  option.  This limitation currently affects OpenBSD before version 4.0. It              is always allowed to have more than one dhcp-range in a single subnet. The  optional              network-id is a alphanumeric label which marks this network so that dhcp options may              be specified on a per-network basis.  When it  is  prefixed  with  ’net:’  then  its              meaning changes from setting a tag to matching it. Only one tag may be set, but more              than one tag may be matched.  The end address may be replaced by the keyword  static              which tells dnsmasq to enable DHCP for the network specified, but not to dynamically              allocate IP addresses. Only hosts which have static addresses given via dhcp-host or              from /etc/ethers will be served.

-G,             --dhcp-host=[ ][,id:|*][,net: ][, ][,][,][,ignore] Specify per  host parameters for the DHCP server. This allows a machine with a par‐ ticular hardware address to be always allocated the same hostname, IP  address  and lease time. A hostname specified like this overrides any supplied by the DHCP client on the machine. It is also allowable to ommit the hardware address and include  the hostname, in  which  case  the IP address and lease times will apply to any machine claiming that name. For example  --dhcp-host=00:20:e0:3b:13:af,wap,infinite  tells dnsmasq to  give  the machine with hardware address 00:20:e0:3b:13:af the name wap, and an infinite DHCP lease. --dhcp-host=lap,192.168.0.199 tells dnsmasq to  always allocate the machine lap the IP address 192.168.0.199. Addresses allocated like this are not constrained to be in the range given by the --dhcp-range option,  but  they must be on the network being served by the DHCP server. It is allowed to use client identifiers rather than hardware addresses to  identify  hosts  by  prefixing  with ’id:’. Thus: --dhcp-host=id:01:02:03:04,..... refers to the host with client iden‐ tifier 01:02:03:04. It is also allowed to specify the client ID as text, like this: --dhcp-host=id:clientidastext,..... The special  option  id:*  means  "ignore any              client-id and use MAC addresses only." This is useful  when  a  client  presents  a              client-id sometimes but not others. If a name appears in /etc/hosts, the associated address can be allocated to a DHCP lease, but only if a --dhcp-host option specify‐ ing the name also exists. The special keyword "ignore" tells dnsmasq to never offer a DHCP lease to a machine. The machine can be specified by hardware address, client ID or  hostname,  for  instance --dhcp-host=00:20:e0:3b:13:af,ignore This is useful when there is another DHCP server on the network  which  should  be  used  by  some machines. The net:  sets  the  network-id  tag whenever this dhcp-host directive is in use. This can be used to selectively send DHCP  options  just  for this host. Ethernet addresses (but not client-ids) may have wildcard bytes, so for example --dhcp-host=00:20:e0:3b:13:*,ignore will cause dnsmasq to ignore a range of              hardware addresses. Note that the "*" will need to be escaped or quoted on a command line, but not in the configuration file. Hardware addresses normally match any net‐ work (ARP) type, but it is possible to restrict them to a single ARP type by preced‐ ing  them    with    the    ARP-type    (in    HEX)    and    "-". so   --dhcp- host=06-00:20:e0:3b:13:af,1.2.3.4 will  only  match  a Token-Ring hardware address, since the ARP-address type for token ring is 6.

-Z, --read-ethers Read /etc/ethers for information about hosts for the DHCP  server. The format  of              /etc/ethers  is  a hardware address, followed by either a hostname or dotted-quad IP              address. When read by dnsmasq these lines have exactly the same effect  as  --dhcp- host options containing the same information.

-O,                          --dhcp-option=[,[,]][vendor:[],][ |option:<opt-name>],[ [, ]] Specify different  or extra options to DHCP clients. By default, dnsmasq sends some standard options to DHCP clients, the netmask and broadcast address are set to  the same as  the  host running dnsmasq, and the DNS server and default route are set to              the address of the machine running dnsmasq. If the domain name option has been set, that is  sent. This configuration allows these defaults to be overridden, or other options specified. The option, to be sent may be given as a decimal  number  or  as              "option:&lt;option-name&gt;"  The  option  numbers are specified in RFC2132 and subsequent RFCs. The set of option-names known by dnsmasq can be discovered by running "dnsmasq             --help  dhcp". For example,  to  set  the default route option to 192.168.4.4, do              --dhcp-option=3,192.168.4.4 or --dhcp-option = option:router, 192.168.4.4 and to set the time-server address to 192.168.0.4, do --dhcp-option = 42,192.168.0.4 or --dhcp- option = option:ntp-server, 192.168.0.4 The special address 0.0.0.0 is taken to mean "the address of the machine running dnsmasq". Data types allowed are comma separated dotted-quad IP addresses, a decimal number, colon-separated hex digits and  a  text string. If the optional network-ids are given then this option is only sent when all the network-ids are matched.

Special processing is done on a text argument for option 119, to conform  with  RFC 3397. Text or dotted-quad IP addresses as arguments to option 120 are handled as per RFC 3361. Dotted-quad IP addresses which are followed by a slash and then a netmask size are encoded as described in RFC 3442.

Be careful: no checking is done that the correct type of data for the option number is sent, it is quite possible to persuade dnsmasq to generate illegal DHCP  packets with injudicious use of this flag. When the value is a decimal number, dnsmasq must determine how large the data item is. It does this by examining the  option  number and/or the  value,  but can be overridden by appending a single letter flag as fol‐ lows: b = one byte, s = two bytes, i = four bytes. This is mainly useful with encap‐ sulated vendor  class  options (see below) where dnsmasq cannot determine data size from the option number. Option data which consists solely of  periods  and  digits will be  interpreted  by  dnsmasq  as an IP address, and inserted into an option as              such. To force a literal string, use quotes. For instance when using option  66  to              send  a  literal  IP  address  as  TFTP  server  name, it is necessary to do --dhcp- option=66,"1.2.3.4"

Encapsulated Vendor-class options may also be specified  using  --dhcp-option:  for instance --dhcp-option=vendor:PXEClient,1,0.0.0.0  sends  the  encapsulated  vendor class-specific option  "mftp-address=0.0.0.0"  to  any  client  whose  vendor-class matches "PXEClient". The vendor-class matching is substring based (see --dhcp-ven‐             dorclass for details). If a vendor-class option (number 60) is sent by dnsmasq, then that is  used  for  selecting encapsulated options in preference to any sent by the client. It is possible  to  omit  the  vendorclass  completely;  --dhcp-option=ven‐ dor:,1,0.0.0.0 in  which  case the encapsulated option is always sent. The address 0.0.0.0 is not treated specially in encapsulated vendor class options.

--dhcp-option-force=[<network-id>,[<network-id>,]][vendor:[<vendor- class>],] ,[ [, ]] This works in exactly the same way as --dhcp-option except  that  the  option  will always be  sent,  even  if  the client does not ask for it in the parameter request list. This is sometimes needed, for example when sending options to PXELinux.

-U, --dhcp-vendorclass=<network-id>,<vendor-class> Map from a vendor-class string to a network id tag. Most DHCP  clients  provide  a              "vendor  class"  which represents, in some sense, the type of host. This option maps vendor classes to tags, so that DHCP options may be selectively delivered to differ‐ ent classes  of hosts. For example dhcp-vendorclass=printers,Hewlett-Packard JetDi‐ rect will allow options to be set only for HP printers like so: --dhcp-option=print‐ ers,3,192.168.4.4 The  vendor-class string is substring matched against the vendor- class supplied by the client, to allow fuzzy matching.

-j, --dhcp-userclass=<network-id>,<user-class> Map from a user-class string to a network id tag (with substring matching, like ven‐             dor  classes). Most DHCP clients provide a "user class" which is configurable. This option maps user classes to tags, so that DHCP options may be selectively delivered to different  classes  of  hosts. It is possible, for instance to use this to set a             different printer server for hosts in the class "accounts" than  for  hosts  in  the class "engineering".

-4, --dhcp-mac=<network-id>,<MAC address> Map from  a MAC address to a network-id tag. The MAC address may include wildcards. For example --dhcp-mac=3com,01:34:23:*:*:* will set the tag  "3com"  for  any  host whose MAC address matches the pattern.

--dhcp-circuitid=<network-id>,<circuit-id>, --dhcp-remoteid=<network-id>,<remote-id> Map from  RFC3046 relay agent options to network-id tags. This data may be provided by DHCP relay agents. The circuit-id or remote-id is normally given as  colon-sepa‐ rated hex, but is also allowed to be a simple string. If an exact match is achieved between the circuit or agent ID and one provided by a relay agent,  the  network-id tag is set.

--dhcp-subscrid=<network-id>,<subscriber-id> Map from RFC3993 subscriber-d relay agent options to network-id tags.

-J, --dhcp-ignore=<network-id>[,<network-id>] When all  the  given network-ids match the set of network-ids derived from the net, host, vendor and user classes, ignore the host and do not allocate it a DHCP lease.

--dhcp-ignore-name[=<network-id>[,<network-id>]] When all  the  given network-ids match the set of network-ids derived from the net, host, vendor and user classes, ignore any hostname provided by the host. Note that, unlike dhcp-ignore,  it is permissable to supply no netid tags, in which case DHCP- client supplied hostnames are always ignored, and DHCP hosts are added to  the  DNS using only  dhcp-host  configuration  in dnsmasq and the contents of /etc/hosts and /etc/ethers.

-M, --dhcp-boot=[net:<network-id>,] ,[ [, ]] Set BOOTP options to be returned by the DHCP server. Server name  and  address  are optional: if  not  provided,  the  name  is  left empty, and the address set to the address of the machine running dnsmasq. If dnsmasq is providing a TFTP service (see              --enable-tftp  )  then only the filename is required here to enable network booting. If the optional network-id(s) are given, they must match for this configuration  to              be sent. Note that network-ids are prefixed by "net:" to distinguish them. -X, --dhcp-lease-max= Limits dnsmasq  to the specified maximum number of DHCP leases. The default is 150. This limit is to prevent DoS attacks from hosts which create thousands of leases and use lots of memory in the dnsmasq process.

-K, --dhcp-authoritative Should be  set  when  dnsmasq  is definitely the only DHCP server on a network. It             changes the behaviour from strict RFC compliance so that DHCP  requests  on  unknown leases from  unknown  hosts  are  not ignored. This allows new hosts to get a lease without a tedious timeout under all circumstances. It also allows dnsmasq to rebuild its lease database without each client needing to reaquire a lease, if the database is lost.

-3, --bootp-dynamic Enable dynamic allocation of IP addresses to BOOTP clients. Use this  with  care, since each  address  allocated  to  a BOOTP client is leased forever, and therefore becomes permanently unavailable for re-use by other hosts.

-5, --no-ping By default, the DHCP server will attempt to ensure that an address in  not  in  use before allocating  it  to a host. It does this by sending an ICMP echo request (aka             "ping") to the address in question. If it gets  a  reply,  then  the  address  must already be  in  use,  and another is tried. This flag disables this check. Use with caution.

--log-dhcp Extra logging for DHCP: log all the options sent to DHCP clients and the netid tags used to determine them.

-l, --dhcp-leasefile= Use the specified file to store DHCP lease information. If this option is given but no dhcp-range option is given then dnsmasq version 1 behaviour  is  activated. The file given is assumed to be an ISC dhcpd lease file and parsed for leases which are then added to the DNS system if they have a hostname. This functionality  may  have been excluded  from  dnsmasq at compile time, in which case an error will occur. In             any case note that ISC leasefile integration is a deprecated feature. It should not be used in new installations, and will be removed in a future release.

-6 --dhcp-script= Whenever a new DHCP lease is created, or an old one destroyed, the binary specified by this option is run. The arguments to the process are "add", "old" or "del",  the MAC address  of the host (or " "), the IP address, and the hostname, if known. "add" means a lease has been created, "del" means it has been destroyed, "old" is a              notification  of an existing lease when dnsmasq starts or a change to MAC address or              hostname of an existing lease (also, lease length or expiry and client-id, if lease‐              file-ro  is  set). The process is run as root (assuming that dnsmasq was originally             run as root) even if dnsmasq is configured to change UID to  an  unprivileged  user. The environment is inherited from the invoker of dnsmasq, and if the host provided a             client-id, this is stored in the  environment  variable  DNSMASQ_CLIENT_ID. If the client provides  vendor-class or user-class information, these are provided in DNS‐ MASQ_VENDOR_CLASS and DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn variables, but  only for "add"  actions  or  "old"  actions when a host resumes an existing lease, since these data are not held in dnsmasq’s lease database. If dnsmasq was  compiled  with HAVE_BROKEN_RTC, then  the  length  of  the  lease  (in  seconds) is stored in DNS‐ MASQ_LEASE_LENGTH, otherwise  the  time  of  lease  expiry  is   stored   in   DNS‐ MASQ_LEASE_EXPIRES. If a lease used to have a hostname, which is removed, an "old" event is generated with the new state of the lease, ie no name, and the former name is provided  in the environment variable DNSMASQ_OLD_HOSTNAME. All file decriptors are closed except stdin, stdout and stderr which are open to /dev/null  (except  in              debug  mode). The script is not invoked concurrently: if subsequent lease changes occur, the script is not invoked again until any existing invocation exits. At dns‐ masq startup,  the  script will be invoked for all existing leases as they are read from the lease file. Expired leases will be called with "del" and others with "old". must be an absolute pathname, no PATH search occurs.

-9, --leasefile-ro Completely suppress  use  of the lease database file. The file will not be created, read, or written. Change the way the lease-change script (if one  is  provided)  is              called,  so  that  the  lease  database may be maintained in external storage by the script. In addition to the invocations  given  in  --dhcp-script  the  lease-change script is  called  once,  at dnsmasq startup, with the single argument "init". When called like this the script should write the saved state of the lease database,  in              dnsmasq  leasefile  format,  to  stdout  and  exit with zero exit code. Setting this option also forces the leasechange script to be called on changes to the  client-id and lease length and expiry time.

--bridge-interface=, [, ] Treat DHCP request packets arriving at any of the interfaces as if they had arrived at. This option is only available on FreeBSD and Dragonfly BSD, and is necessary when using "old style" bridging, since packets arrive at tap inter‐ faces which don’t have an IP address.

-s, --domain= Specifies the domain for the DHCP server. This has two effects; firstly  it  causes the DHCP server to return the domain to any hosts which request it, and secondly it              sets the domain which it is legal for DHCP-configured hosts to claim. The intention is to constrain hostnames so that an untrusted host on the LAN cannot advertise its name via dhcp as e.g. "microsoft.com" and capture traffic not meant for it. If no              domain  suffix  is  specified,  then any DHCP hostname with a domain part (ie with a              period) will be disallowed and logged. If suffix is specified, then hostnames with a             domain  part  are allowed, provided the domain part matches the suffix. In addition, when a suffix is set then hostnames without a domain part have the suffix added  as              an  optional  domain part. Eg on my network I can set --domain=thekelleys.org.uk and have a machine whose DHCP hostname is "laptop". The IP address for that machine  is              available  from  dnsmasq  both  as  "laptop"  and "laptop.thekelleys.org.uk". If the domain is given as "#" then the domain is read from the first "search" directive in              /etc/resolv.conf (or equivalent).

--enable-tftp Enable the TFTP server function. This is deliberately limited to that needed to net- boot a client: Only reading is allowed, and only in binary/octet mode. The tsize and blksize extensions are supported.

--tftp-root= Look for files to transfer using TFTP relative to the given directory. When this is             set, TFTP paths which include ".." are rejected, to stop clients getting outside the specified root. Absolute paths  (starting  with /) are allowed, but they must be              within the tftp-root.

--tftp-secure Enable TFTP secure mode: without this, any file which is readble by the dnsmasq pro‐ cess under normal unix access-control rules is available via TFTP. When the --tftp- secure flag is given, only files owned by the user running the dnsmasq process  are accessible. If dnsmasq  is being run as root, different rules apply: --tftp-secure has no effect, but only files which have the world-readable bit set are accessible. It is  not  recommended to run dnsmasq as root with TFTP enabled, and certainly not without specifying --tftp-root. Doing so can expose any world-readable file on  the server to any host on the net.

--tftp-max= Set the maximum number of concurrent TFTP connections allowed. This defaults to 50. When serving a large number of TFTP connections, per-process file descriptor limits may be encountered. Dnsmasq needs one file descriptor for each concurrent TFTP con‐ nection and one file descriptor per unique file (plus a few others). So serving the same file  simultaneously  to n clients will use require about n + 10 file descrip‐ tors, serving different files simultaneously to n clients will require about (2*n) + 10 descriptors.

--tftp-no-blocksize Stop the  TFTP  server  from negotiating the "blocksize" option with a client. Some buggy clients request this option but then behave badly when it is granted.

-C, --conf-file= Specify a different configuration file. The conf-file option is also allowed in con‐ figuration files, to include multiple configuration files.

-7, --conf-dir= Read all the files in the given directory as configuration files. Files whose names end in ~ or start with. or start and end with # are skipped. This flag may be given on the command line or in a configuration file.

CONFIG FILE
At startup,  dnsmasq  reads  /etc/dnsmasq.conf,  if  it  exists. (On FreeBSD, the file is      /usr/local/etc/dnsmasq.conf ) (but see the -C and -7 options.) The format of this file con‐ sists of  one option per line, exactly as the long options detailed in the OPTIONS section but without the leading "--". Lines starting with # are comments and ignored. For options which may only be specified once, the configuration file overrides the command line. Quot‐ ing is allowed in a config file: between " quotes the special meanings of ,:.  and  #  are       removed  and  the following escapes are allowed: \\ \" \t \a \b \r and \n. The later corre‐ sponding to tab, bell, backspace, return and newline.

LIMITS
The default values for resource limits in dnsmasq are generally conservative, and appropri‐ ate for embedded router type devices with slow processors and limited memory. On more capa‐ ble hardware, it is possible to increase the limits, and handle many more clients. The fol‐ lowing applies to dnsmasq-2.37: earlier versions did not scale as well.

Dnsmasq is capable of handling DNS and DHCP for at least a thousand clients. Clearly to do       this  the  value  of --dhcp-lease-max must be increased, and lease times should not be very short (less than one hour). The value of --dns-forward-max can be increased: start with it       equal  to  the  number of clients and increase if DNS seems slow. Note that DNS performance depends too on the performance of the upstream nameservers. The size of the DNS cache  may be increased:  the  hard  limit  is 10000 names and the default (150) is very low. Sending SIGUSR1 to dnsmasq makes it log information which is useful for tuning the cache size. See the NOTES section for details.

The built-in TFTP server is capable of many simultaneous file transfers: the absolute limit is related to the number of file-handles allowed to a  process  and  the  ability  of  the select system  call  to cope with large numbers of file handles. If the limit is set too high using --tftp-max it will be scaled down and the actual limit logged at start-up. Note that more  transfers are possible when the same file is being sent than when each transfer sends a different file.

It is possible to use dnsmasq to block Web advertising by using a list of known  banner-ad servers, all resolving to 127.0.0.1 or 0.0.0.0, in /etc/hosts or an additional hosts file. The list can be very long, dnsmasq has been tested successfully with  one  million  names. That size file needs a 1GHz processor and about 60Mb of RAM.

FILES

 * /etc/dnsmasq.conf
 * /usr/local/etc/dnsmasq.conf
 * /etc/resolv.conf
 * /etc/hosts
 * /etc/ethers
 * /var/lib/misc/dnsmasq.leases
 * /var/db/dnsmasq.leases
 * /var/run/dnsmasq.pid

AUTHOR
This manual page was written by Simon Kelley &lt;simon@thekelleys&gt;.