dnsmasq manpage

Navigation

computing: software: dnsmasq: manpage

Text

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=<file>
             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=<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[=<lines>]
             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=<path>
             Specify  an  alternate  path  for  dnsmasq  to  record  its  process-id in. Normally
             /var/run/dnsmasq.pid.

      -u, --user=<username>
             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=<groupname>
             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=<port>
             Listen on <port> instead of the standard DNS port (53). Useful mainly for debugging.

      -P, --edns-packet-max=<size>
             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=<query_port>
             Send outbound DNS queries from, and listen for their replies on,  the  specific  UDP
             port  <query_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=<interface name>
             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=<interface name>
             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=<interface name>
             Do  not provide DHCP or TFTP on the specified interface, but do provide DNS service.

      -a, --listen-address=<ipaddr>
             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=<old-ip>,<new-ip>[,<mask>]
             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=<ipaddr>
             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=<file>
             Read  the  IP  addresses  of  the  upstream  nameservers  from  <file>,  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>]/[domain/]][<ipaddr>[#<port>][@<source>[#<port>]]]
             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>/[domain/]<ipaddr>
             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=<mx name>[[,<hostname>],<preference>]
             Return an MX record named <mx name> 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=<hostname>
             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=<_service>.<_prot>.[<domain>],[<target>[,<port>[,<priority>[,<weight>]]]]
             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=<name>[[,<text>],<text>]
             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=<name>[,<target>]
             Return a PTR DNS record.

      --interface-name=<name>,<interface>
             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=<cachesize>
             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=<queries>
             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,]<start-addr>,<end-addr>[[,<netmask>],<broad‐
      cast>][,<default lease time>]
             Enable  the  DHCP server. Addresses will be given out from the range <start-addr> to
             <end-addr> 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=[<hwaddr>][,id:<client_id>|*][,net:<netid>][,<ipaddr>][,<host‐
      name>][,<lease_time>][,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:<network-id>  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=[<network-id>,[<network-id>,]][vendor:[<vendor-
      class>],][<opt>|option:<opt-name>],[<value>[,<value>]]
             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:<option-name>"  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>],]<opt>,[<value>[,<value>]]
             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>,]<filename>,[<servername>[,<server address>]]
             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=<number>
             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=<path>
             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=<path>
             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 "<null>"), 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".
             <path> 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=<interface>,<alias>[,<alias>]
             Treat  DHCP request packets arriving at any of the <alias> interfaces as if they had
             arrived at <interface>. 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=<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=<directory>
             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=<connections>
             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=<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=<directory>
             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.

NOTES

      When it receives a SIGHUP, dnsmasq clears  its  cache  and  then  re-loads  /etc/hosts  and
      /etc/ethers.   If  --no-poll is set SIGHUP also re-reads /etc/resolv.conf.  SIGHUP does NOT
      re-read the configuration file.

      When it receives a SIGUSR1, dnsmasq writes cache statistics to the system  log.  It  writes
      the  cache  size,  the number of names which have had to removed from the cache before they
      expired in order to make room for new names and the total number of names  that  have  been
      inserted  into  the cache. In --no-daemon mode or when full logging is enabled (-q), a com‐
      plete dump of the contents of the cache is made.

      Dnsmasq is a DNS query forwarder: it it not  capable  of  recursively  answering  arbitrary
      queries  starting  from  the  root  servers  but forwards such queries to a fully recursive
      upstream DNS server which is typically provided  by  an  ISP.  By  default,  dnsmasq  reads
      /etc/resolv.conf  to  discover  the IP addresses of the upstream nameservers it should use,
      since the information is typically stored there. Unless --no-poll is used,  dnsmasq  checks
      the  modification time of /etc/resolv.conf (or equivalent if --resolv-file is used) and re-
      reads it if it changes. This allows the DNS servers to be set dynamically by  PPP  or  DHCP
      since  both protocols provide the information.  Absence of /etc/resolv.conf is not an error
      since it may not have been created before a PPP connection  exists.  Dnsmasq  simply  keeps
      checking in case /etc/resolv.conf is created at any time. Dnsmasq can be told to parse more
      than one resolv.conf file. This is useful on a laptop, where both PPP and DHCP may be used:
      dnsmasq  can  be  set to poll both /etc/ppp/resolv.conf and /etc/dhcpc/resolv.conf and will
      use the contents of whichever changed last, giving automatic switching between DNS servers.

      Upstream  servers  may  also be specified on the command line or in the configuration file.
      These server specifications optionally take a domain name which tells dnsmasq to  use  that
      server only to find names in that particular domain.

      In  order  to  configure  dnsmasq  to act as cache for the host on which it is running, put
      "nameserver 127.0.0.1" in /etc/resolv.conf to force local processes to send queries to dns‐
      masq.  Then  either specify the upstream servers directly to dnsmasq using --server options
      or put their addresses real in another file, say /etc/resolv.dnsmasq and run  dnsmasq  with
      the  -r  /etc/resolv.dnsmasq option. This second technique allows for dynamic update of the
      server addresses by PPP or DHCP.

      Addresses in /etc/hosts will "shadow"  different  addresses  for  the  same  names  in  the
      upstream  DNS,  so  "mycompany.com  1.2.3.4"  in  /etc/hosts  will  ensure that queries for
      "mycompany.com" always return 1.2.3.4 even if queries in the upstream DNS  would  otherwise
      return  a different address. There is one exception to this: if the upstream DNS contains a
      CNAME which points to a shadowed name, then looking  up  the  CNAME  through  dnsmasq  will
      result  in  the  unshadowed address associated with the target of the CNAME. To work around
      this, add the CNAME to /etc/hosts so that the CNAME is shadowed too.

      The network-id system works as follows: For each DHCP request, dnsmasq collects  a  set  of
      valid  network-id  tags, one from the dhcp-range used to allocate the address, one from any
      matching dhcp-host and possibly many from matching vendor classes and user classes sent  by
      the  DHCP  client. Any dhcp-option which has network-id tags will be used in preference  to
      an untagged dhcp-option, provided that _all_ the tags match somewhere in the set  collected
      as  described above. The prefix ’#’ on a tag means ’not’ so --dhcp=option=#purple,3,1.2.3.4
      sends the option when the network-id tag purple is not in the set of valid tags.

      If the network-id in a dhcp-range is prefixed with ’net:’ then  its  meaning  changes  from
      setting a tag to matching it. Thus if there is more than dhcp-range on a subnet, and one is
      tagged with a network-id which is set (for instance from a vendorclass option)  then  hosts
      which set the netid tag will be allocated addresses in the tagged range.

      The  DHCP  server  in  dnsmasq  will function as a BOOTP server also, provided that the MAC
      address and IP address for clients are given, either using dhcp-host configurations  or  in
      /etc/ethers  , and a dhcp-range configuration option is present to activate the DHCP server
      on a particular network. (Setting --bootp-dynamic removes the need for static address  map‐
      pings.)  The filename parameter in a BOOTP request is matched against netids in dhcp-option
      configurations, as is the tag "bootp", allowing some control over the options  returned  to
      different classes of hosts.

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

SEE ALSO

hosts(5), resolver(5)

AUTHOR

This manual page was written by Simon Kelley <simonspam@spamthekelleysspam.spamorg.uk>.