DNSMASQ(8)                                                          DNSMASQ(8)



NAME
       dnsmasq - A caching DNS forwarder.

SYNOPSIS
       dnsmasq [OPTION]...

DESCRIPTION
       dnsmasq  is  a  lightweight  DNS forwarder.  It 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 into
       the cache at startup so that local hostnames which do not appear in the
       global  DNS  can  be  resolved.  It can also read hostnames from a DHCP
       leases file so that local hosts which have addresses allocated by  DHCP
       can be named.

       dnsmasq supports IPv6.

       dnsmasq  is lightweight and easy to configure. It is intended as be run
       on small router/firewalls and  provide a DNS service to a LAN.

OPTIONS
       Note that in general missing parameters  are  allowed  and  switch  off
       functions, for instance "--pid-file=" disables writing a PID 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.  At
              most one additional hosts file may be given.

       -T, --local-ttl=<time>
              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 situ-
              ations.  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 circum-
              stances.

       -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.

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

       -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
              priviledges after startup by changing id to another  user.  Nor-
              mally  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.

       -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. More than one  interface
              may be specified. Dnsmasq always listens on the loopback (local)
              interface. If no -i flags are  given,  dnsmasq  listens  on  all
              available interfaces unless overridden by -a or -I flags.

       -I, --except-interface=<interface name>
              Do not listen on the specified interface.

       -a, --listen-address
              Listen  only  on  the given IP address. As with -i more than one
              address may be specified. Unlike -i the  loopback  interface  is
              not  special: if dnsmasq is to listen on the loopback interface,
              it's IP, 127.0.0.1, must be explicitly given. If no -a flags are
              given,  dnsmasq listens on all available interfaces unless over-
              ridden by -i or -I flags.

       -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  resolved  to  the  IP
              address in dotted-quad form.

       -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 Versign in September 2003 when they started return-
              ing 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 returnd 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 relevant 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, sub-
              sequent 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 /etc/dnsmasq.conf.

       -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.

       -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  knowm  from /etc/hosts or DHCP then a "not found" answer is
              returned.

       -S,
       --server=[/[<domain>]/[domain/]][<ipaddr>[#<port>][@<source>[#<port>]]]
              Specify IP address of upsream 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 nameserver on your network which deals with names of
              the form xxx.internal.thekelleys.org.uk at 192.168.1.1 then giv-
              ing   the  flag  -S /internal.thekelleys.org.uk/192.168.1.1 will
              send all queries  for  internal  machines  to  that  nameserver,
              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 without 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  dnsmasq 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 syn-
              onym for server to make  configuration  files  clearer  in  this
              case.

              The  optional second IP address after the @ character tells dns-
              masq how to set the source address of the queries to this  name-
              server.  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 over-
              ride this for individual names. A common use of this is to redi-
              rect  the  entire  doubleclick.net domain to some friendly local
              web server to avoid banner ads.

       -m, --mx-host=<mx name>
              Return an MX record named <mx name> pointing to the host  speci-
              fied  in the --mx-target switch or, if that switch is not given,
              the host on which dnsmasq is running. This is useful for direct-
              ing mail from systems on a LAN to a central server.

       -t, --mx-target=<hostname>
              Specify  target for the MX record returned by dnsmasq. See --mx-
              host. Note that to turn on the MX  function,  at  least  one  of
              --mx-host  and --mx-target must be set. If only one of --mx-host
              and --mx-target is set, the other defaults to  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 the DHCP leases  file.

       -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 the DHCP leases file.

       -c, --cache-size=<cachesize>
              Set the size of dnsmasq's cache. The default is 150 names.  Set-
              ting 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  forwarding them again. This
              flag disables negative caching.

       -l, --dhcp-lease=<path>
              Read DHCP leases from the specified lease file. The file  is  of
              the  format  created by the ISC dhcp daemon: see dhcpd.leases(5)
              for details. Dnsmasq will re-read the file as  it  changes.  Any
              host  which sets the "hostname" or "client-hostname" option will
              have that name inserted into dnsmasq's cache.

       -s, --domain-suffix=<domain>
              Specifies the domain which hosts read from the DHCP leases  file
              must  have  to be legal. The intention is to constrain hostnames
              so that an untrusted host on the LAN cannot advertise it's  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-suffix=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".

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

CONFIG FILE
       At startup, dnsmasq reads /etc/dnsmasq.conf, if it exists.  The  format
       of  this  file  consists  of  one  option per line, exactly as the long
       options detailed in the OPTIONS section. Lines starting with # are com-
       ments  and  ignored.  For  options  which  may  only be specified once,
       /etc/dnsmasq.conf overrides  the  command  line.  Use  the  --conf-file
       option to specify a different configuration file.

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

       When it receives a SIGUSR1, dnsmasq writes cache statistics to the sys-
       tem 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 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.

       When it receives a SIGUSR2, dnsmasq re-scans network  interfaces.  This
       is  required if it is to listen for queries on newly created interfaces
       or interfaces which have changed IP address. For this facility to work,
       dnsmasq   must  be  told  to  continue  running  as  user  root,  using
       --user=root

       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  typi-
       cally 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 cre-
       ated 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
       /etc/dnsmasq.conf. 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 dnsmasq. 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.

FILES
       /etc/dnsmasq.conf

       /etc/resolv.conf

       /etc/hosts

       /var/lib/dhcp/dhcp.leases

       /var/run/dnsmasq.pid

SEE ALSO
       dhcp.leases(5), hosts(5), resolver(5)

AUTHOR
       This manual page was written by Simon Kelley <simon@thekelleys.org.uk>.





                                                                    DNSMASQ(8)