Man Pages

dnsmasq(8) - phpMan dnsmasq(8) - phpMan

Command: man perldoc info search(apropos)  


DNSMASQ(8)                                                          DNSMASQ(8)



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 and multiple networks.  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 all functions and a minimal router-advertisement daemon.

OPTIONS
       Note  that  in  general missing parameters are allowed and switch off functions, for instance "--pid-file" dis-
       ables 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.

       --test Read  and  syntax  check configuration file(s). Exit with code 0 if all is OK, or a non-zero code other-
              wise. Do not start up dnsmasq.

       -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. If a directory is
              given, then read all the files contained in that directory.

       -E, --expand-hosts
              Add the domain to simple names (without a period) in /etc/hosts in the  same  way  as  for  DHCP-derived
              names. Note that this does not apply to domain names in cnames, PTR records, TXT records etc.

       -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 requester should not itself cache the information. This  is  the
              correct thing to do in almost all situations. 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.

       --neg-ttl=<time>
              Negative  replies  from  upstream servers normally contain time-to-live information in SOA records which
              dnsmasq uses for caching. If the replies from upstream servers omit this information, dnsmasq  does  not
              cache  the  reply. This option gives a default value for time-to-live (in seconds) which dnsmasq uses to
              cache negative replies even in the absence of an SOA record.

       --max-ttl=<time>
              Set a maximum TTL value that will be handed out to clients. The specified maximum TTL will be  given  to
              clients instead of the true TTL value if it is lower. The true TTL value is however kept in the cache to
              avoid flooding the upstream DNS servers.

       -k, --keep-in-foreground
              Do not go into the background at startup but otherwise run as normal. This is intended for use when dns-
              masq 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 com-
              plete 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 facility given contains at least one '/' character, it is taken to be
              a  filename,  and dnsmasq logs to the given file, instead of syslog. If the facility is '-' then dnsmasq
              logs to stderr.  (Errors whilst reading configuration will still go to syslog, but  all  output  from  a
              successful  startup,  and all output whilst running, will go exclusively to the file.) When logging to a
              file, dnsmasq will close and reopen the file when it receives SIGUSR2. This allows the log  file  to  be
              rotated without stopping dnsmasq.

       --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 syslog, 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). Setting this to zero completely disables DNS
              function, leaving only DHCP and/or TFTP.

       -P, --edns-packet-max=<size>
              Specify the largest EDNS.0 UDP packet which is supported by the DNS forwarder. Defaults to  4096,  which
              is the RFC5625-recommended size.

       -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 random ports. NOTE that using this option will make dnsmasq  less  secure  against  DNS
              spoofing attacks but it may be faster and use less resources.  Setting this option to zero makes dnsmasq
              use a single port allocated to it by the OS: this was the default behaviour in versions prior to 2.43.

       --min-port=<port>
              Do not use ports less than that given as source for outbound DNS queries. Dnsmasq picks random ports  as
              source  for  outbound queries: when this option is given, the ports used will always to larger than that
              specified. Useful for systems behind firewalls.

       -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 interfaces (eg "eth1:0") cannot be used with --interface or --except-inter-
              face 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-interface options always override the oth-
              ers.

       -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 listening on. About the only time when this is useful is  when  running  another  name-
              server  (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.

       --bind-dynamic
              Enable a network mode which is a hybrid between --bind-interfaces and the  default.  Dnsmasq  binds  the
              address  of  individual  interfaces,  allowing  multiple  dnsmasq  instances,  but  if new interfaces or
              addresses appear, it automatically listens on those (subject to any access-control configuration).  This
              makes  dynamically  created  interfaces  work  in  the same way as the default. Implementing this option
              requires non-standard networking APIs and it is only available under Linux. On other platforms it falls-
              back to --bind-interfaces mode.

       -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 subnet. This allows for a server  to have multiple addresses  in  /etc/hosts  corre-
              sponding  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>]|[<start-ip>-<end-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". If the old IP is given as range, then only addresses in the
              range,       rather       than       a       whole       subnet,        are        re-written.        So
              --alias=192.168.0.10-192.168.0.40,10.0.0.0,255.255.255.0      maps     192.168.0.10->192.168.0.40     to
              10.0.0.10->10.0.0.40

       -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 for-
              mat 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, 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 configura-
              tion file.

       -1, --enable-dbus[=<service-name>]
              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. If the service name is given, dnsmasq provides service  at  that  name,  rather
              than the default which is uk.org.thekelleys.dnsmasq

       -o, --strict-order
              By  default, dnsmasq will send queries to any of the upstream servers it knows about and tries to favour
              servers that 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

       --all-servers
              By  default,  when dnsmasq has more than one upstream server available, it will send queries to just one
              server. Setting this flag forces dnsmasq to send all queries to all available servers.  The  reply  from
              the server which answers first will be returned to the original requester.

       --stop-dns-rebind
              Reject  (and log) addresses from upstream nameservers which are in the private IP ranges. This blocks an
              attack where a browser behind a firewall is used to probe machines on the local network.

       --rebind-localhost-ok
              Exempt 127.0.0.0/8 from rebinding checks. This address range is returned by realtime black hole servers,
              so blocking it may disable these services.

       --rebind-domain-ok=[<domain>]|[[/<domain>/[<domain>/]
              Do  not  detect  and  block  dns-rebind on queries to these domains. The argument may be either a single
              domain, or multiple  domains  surrounded  by  '/',  like  the  --server  syntax,  eg.   --rebind-domain-
              ok=/domain1/domain2/domain3/

       -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 A or AAAA 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-ip>|<interface>[#<port>]]
              Specify IP address of upstream servers  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.inter-
              nal.thekelleys.org.uk at 192.168.1.1 then giving  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.

              More  specific  domains  take  precendence  over less specific domains, so: --server=/google.com/1.2.3.4
              --server=/www.google.com/2.3.4.5 will send queries for *.google.com to 1.2.3.4, except  *www.google.com,
              which will go to 2.3.4.5

              The  special  server  address  '#'  means,  "use  the standard servers", so --server=/google.com/1.2.3.4
              --server=/www.google.com/# will send queries for *.google.com to 1.2.3.4, except  *www.google.com  which
              will be forwarded as usual.

              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 synonym for server to make configuration files clearer in this
              case.

              IPv6 addresses may include a %interface scope-id, eg fe80::202:a412:4512:7bbf%eth0.

              The optional string after the @ character tells dnsmasq how to set the source of  the  queries  to  this
              nameserver.  It  should be an ip-address, which should belong to the machine on which dnsmasq is running
              otherwise this server line will be logged and then ignored, or an interface name. If an  interface  name
              is  given,  then queries to the server will be forced via that interface; if an ip-address is given then
              the source address of the queries will be set to that address.  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. Forcing queries to an interface is not implemented on all platforms  supported  by  dns-
              masq.

       -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 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 systems 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 numbers are in a different order. More than one SRV record for a  given  service/domain  is
              allowed, all that match are returned.

       --host-record=<name>[,<name>....][<IPv4-address>],[<IPv6-address>]
              Add  A, AAAA and PTR records to the DNS. This adds one or more names to the DNS with associated IPv4 (A)
              and IPv6 (AAAA) records. A name may appear in more than one host-record and therefore be  assigned  more
              than  one  address. Only the first address creates a PTR record linking the address to the name. This is
              the same rule as is used reading hosts-files.  host-record options are  considered  to  be  read  before
              host-files,  so  a  name  appearing there inhibits PTR-record creation if it appears in hosts-file also.
              Unlike hosts-files, names are not expanded, even when expand-hosts is in effect. Short  and  long  names
              may         appear         in         the         same         host-record,         eg.          --host-
              record=laptop,laptop.thekelleys.org,192.168.0.1,1234::100

       -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,
              delimited  by  commas;  use quotes to put commas into a string. Note that the maximum length of a single
              string is 255 characters, longer strings are split into 255 character chunks.

       --ptr-record=<name>[,<target>]
              Return a PTR DNS record.

       --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>]
              Return an NAPTR DNS record, as specified in RFC3403.

       --cname=<cname>,<target>
              Return a CNAME record which indicates that <cname> is really <target>. There are significant limitations
              on  the  target;  it  must  be a DNS name which is known to dnsmasq from /etc/hosts (or additional hosts
              files), from DHCP or from another --cname.  If the target does not  satisfy  this  criteria,  the  whole
              cname  is  ignored. The cname must be unique, but it is permissable to have more than one cname pointing
              to the same target.

       --dns-rr=<name>,<RR-number>,[<hex data>]
              Return an arbitrary DNS Resource Record. The number is the type of the record (which is  always  in  the
              C_IN  class).  The value of the record is given by the hex data, which may be of the form 01:23:45 or 01
              23 45 or 012345 or any mixture of these.

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

       --add-mac
              Add  the  MAC  address of the requestor to DNS queries which are forwarded upstream. This may be used to
              DNS filtering by the upstream server. The MAC address can only be added if the requestor is on the  same
              subnet  as the dnsmasq server. Note that the mechanism used to achieve this (an EDNS0 option) is not yet
              standardised, so this should be considered experimental. Also note that exposing MAC addresses  in  this
              way may have security and privacy implications.

       -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 forwarding them again.

       -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 numbers of concurrent queries.

       --proxy-dnssec
              A  resolver  on  a  client machine can do DNSSEC validation in two ways: it can perform the cryptograhic
              operations on the reply it receives, or it can rely on the upstream recursive nameserver to do the vali-
              dation  and  set a bit in the reply if it succeeds. Dnsmasq is not a DNSSEC validator, so it cannot per-
              form the validation role of the recursive nameserver, but it can pass  through  the  validation  results
              from  its  own  upstream nameservers. This option enables this behaviour. You should only do this if you
              trust all the configured upstream nameservers and the network between you and  them.   If  you  use  the
              first  DNSSEC mode, validating resolvers in clients, this option is not required. Dnsmasq always returns
              all the data needed for a client to do validation itself.

       --conntrack
              Read the Linux connection track mark associated with incoming DNS queries and set the same mark value on
              upstream traffic used to answer those queries. This allows traffic generated by dnsmasq to be associated
              with the queries which cause it, useful for bandwidth accounting and firewalling. Dnsmasq must have con-
              ntrack  support  compiled  in  and  the kernel must have conntrack support included and configured. This
              option cannot be combined with --query-port.

       -F,     --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag],]<start-addr>[,<end-addr>][,<mode>][,<netmask>[,<broad-
       cast>]][,<lease time>]

       -F,       --dhcp-range=[tag:<tag>[,tag:<tag>],][set:<tag],]<start-IPv6addr>[,<end-IPv6addr>][,<mode>][,<prefix-
       len>][,<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
              "infinite". If not given, the default lease time is one hour. The minimum lease time is two minutes. For
              IPv6 ranges, the lease time maybe "deprecated"; this sets the preferred lifetime sent in a DHCP lease or
              router advertisement to zero, which causes clients to use other addresses, if available, for new connec-
              tions as a prelude to renumbering.

              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: dnsmasq will determine it from the  interface  configuration.  For  networks  which
              receive  DHCP  service  via  a relay agent, dnsmasq cannot determine the netmask itself, so it should be
              specified, otherwise dnsmasq will have to guess, based on the class (A, B or C) of the network  address.
              The  broadcast  address  is  always optional. It is always allowed to have more than one dhcp-range in a
              single subnet.

              For IPv6, the parameters are slightly different: instead of netmask and broadcast address, there  is  an
              optional  prefix  length.  If not given, this defaults to 64. Unlike the IPv4 case, the prefix length is
              not automatically derived from the interface configuration. The mimimum size of the prefix length is 64.

              The  optional  set:<tag> sets an alphanumeric label which marks this network so that dhcp options may be
              specified on a per-network basis.  When it is prefixed with 'tag:' instead,  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  optional <mode> keyword may be 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.

              For IPv4, the <mode> may be proxy in which case dnsmasq will provide proxy-DHCP on the specified subnet.
              (See pxe-prompt and pxe-service for details.)

              For IPv6, the mode may be some combination of ra-only, slaac, ra-names, ra-stateless.

              ra-only tells dnsmasq to offer Router Advertisement only on this subnet, and not DHCP.

              slaac tells dnsmasq to offer Router Advertisement on this subnet and to set the  A  bit  in  the  router
              advertisement,  so  that the client will use SLAAC addresses. When used with a DHCP range or static DHCP
              address this results in the client having both a DHCP-assigned and a SLAAC address.

              ra-stateless sends router advertisements with the O and A bits set, and provides a stateless  DHCP  ser-
              vice. The client will use a SLAAC address, and use DHCP for other configuration information.

              ra-names  enables a mode which gives DNS names to dual-stack hosts which do SLAAC for IPv6. Dnsmasq uses
              the host's IPv4 lease to derive the name, network segment and MAC address and assumes that the host will
              also have an IPv6 address calculated using the SLAAC algorithm, on the same network segment. The address
              is pinged, and if a reply is received, an AAAA record is added to the DNS for this  IPv6  address.  Note
              that  this is only happens for directly-connected networks, (not one doing DHCP via a relay) and it will
              not work if a host is using privacy extensions.  ra-names can be combined  with ra-stateless and  slaac.


       -G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,set:<tag>][,<ipaddr>][,<hostname>][,<lease_time>][,ignore]
              Specify  per  host  parameters  for  the  DHCP  server. This allows a machine with a particular 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 omit 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 in the same subnet as some valid dhcp-range.  For subnets which don't need  a  pool  of
              dynamically allocated addresses, use the "static" keyword in the dhcp-range declaration.

              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   identifier
              01:02:03:04.  It is also allowed to specify the client ID as text, like this: --dhcp-host=id:clientidas-
              text,.....

              A single dhcp-host may contain an IPv4 address or an IPv6 address,  or  both.  IPv6  addresses  must  be
              bracketed  by  square  brackets thus: --dhcp-host=laptop,[1234::56] Note that in IPv6 DHCP, the hardware
              address is not normally available, so a client must be identified by client-id (called  client  DUID  in
              IPv6-land) or hostname.

              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  specifying  the  name  also  exists.  Only one hostname can be given in a dhcp-host
              option, but aliases are possible by using CNAMEs. (See --cname ).

              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 set:<tag> contruct sets the tag whenever this dhcp-host directive is in use. This  can  be  used  to
              selectively  send DHCP options just for this host. More than one tag can be set in a dhcp-host directive
              (but not in other places where "set:<tag>" is allowed). When a host matches any dhcp-host directive  (or
              one implied by /etc/ethers) then the special tag "known" is set. This allows dnsmasq to be configured to
              ignore requests from unknown machines using --dhcp-ignore=tag:!known 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 network (ARP) type, but it is possible to restrict them to a sin-
              gle  ARP   type   by   preceding   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.

              As a special case, in DHCPv4, it is possible to include more than  one  hardware  address.  eg:  --dhcp-
              host=11:22:33:44:55:66,12:34:56:78:90:12,192.168.0.2  This  allows  an  IP address to be associated with
              multiple hardware addresses, and gives dnsmasq permission to abandon a DHCP lease to one of the hardware
              addresses  when  another one asks for a lease. Beware that this is a dangerous thing to do, it will only
              work reliably if only one of the hardware addresses is active at any time and there is no way  for  dns-
              masq  to enforce this. It is, for instance, useful to allocate a stable IP address to a laptop which has
              both wired and wireless interfaces.

       --dhcp-hostsfile=<path>
              Read DHCP host information from the specified file. If a directory is given, then  read  all  the  files
              contained in that directory. The file contains information about one host per line. The format of a line
              is the same as text to the right of '=' in --dhcp-host. The advantage of storing DHCP  host  information
              in  this  file is that it can be changed without re-starting dnsmasq: the file will be re-read when dns-
              masq receives SIGHUP.

       --dhcp-optsfile=<path>
              Read DHCP option information from the specified file.  If a directory is given, then read all the  files
              contained in that directory. The advantage of using this option is the same as for --dhcp-hostsfile: the
              dhcp-optsfile will be re-read when dnsmasq receives SIGHUP. Note that  it  is  possible  to  encode  the
              information  in  a  --dhcp-boot  flag as DHCP options, using the options names bootfile-name, server-ip-
              address and tftp-server. This allows these to be included in a dhcp-optsfile.

       -Z, --read-ethers
              Read /etc/ethers for information about hosts for the DHCP server. The format of /etc/ethers is  a  hard-
              ware  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. /etc/ethers is  re-
              read when dnsmasq receives SIGHUP. IPv6 addresses are NOT read from /etc/ethers.

       -O,               --dhcp-option=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][vendor:[<vendor-
       class>],][<opt>|option:<opt-name>|option6:<opt>|option6:<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. (Equivalent rules
              apply for IPv6.) 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  (or  [::]
              for  DHCPv6) 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 tags are given then this option is only sent when all the tags 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.

              IPv6 options are specified using the option6: keyword, followed by the option number or option name. The
              IPv6 option name space is disjoint from the IPv4 option name space. IPv6 addresses in  options  must  be
              bracketed with square brackets, eg.  --dhcp-option=option6:ntp-server,[1234::56]


              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 exam-
              ining the option number and/or the value, but can be overridden by appending a  single  letter  flag  as
              follows:  b  =  one  byte, s = two bytes, i = four bytes. This is mainly useful with encapsulated 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 (IPv4 only) 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 sub-
              string based (see --dhcp-vendorclass for details). If a vendor-class option (number 60) is sent by  dns-
              masq,  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=vendor:,1,0.0.0.0 in which case the encap-
              sulated option is always sent.

              Options may be encapsulated (IPv4 only) within other options: for instance --dhcp-option=encap:175, 190,
              iscsi-client0 will send option 175, within which is the option 190. If multiple options are given  which
              are  encapsulated with the same option number then they will be correctly combined into one encapsulated
              option.  encap: and vendor: are may not both be set in the same dhcp-option.

              The final variant on encapsulated  options  is  "Vendor-Identifying  Vendor  Options"  as  specified  by
              RFC3925.  These  are  denoted  like this: --dhcp-option=vi-encap:2, 10, text The number in the vi-encap:
              section is the IANA enterprise number used to identify this option. This form of encapsulation  is  sup-
              ported in IPv6.

              The address 0.0.0.0 is not treated specially in encapsulated options.

       --dhcp-option-force=[tag:<tag>,[tag:<tag>,]][encap:<opt>,][vi-encap:<enterprise>,][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.

       --dhcp-no-override
              (IPv4  only) Disable re-use of the DHCP servername and filename fields as extra option space. If it can,
              dnsmasq moves the boot server and filename information (from dhcp-boot) out of  their  dedicated  fields
              into  DHCP options. This make extra space available in the DHCP packet for options but can, rarely, con-
              fuse old or broken clients. This flag forces "simple and safe" behaviour to avoid  problems  in  such  a
              case.

       -U, --dhcp-vendorclass=set:<tag>,[enterprise:<IANA-enterprise number>,]<vendor-class>
              Map from a vendor-class string to a 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 different classes of hosts. For example dhcp-vendorclass=set:printers,Hewlett-
              Packard JetDirect will allow options to be set only for HP printers  like  so:  --dhcp-option=tag: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. The set: prefix is optional but allowed for consistency.

              Note that in IPv6 only, vendorclasses are namespaced with an IANA-allocated enterprise number.  This  is
              given  with  enterprise:  keyword  and  specifies  that only vendorclasses matching the specified number
              should be searched.

       -j, --dhcp-userclass=set:<tag>,<user-class>
              Map from a user-class string to a tag (with substring matching, like vendor 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=set:<tag>,<MAC address>
              (IPv4 only) Map from a MAC address to a tag. The MAC address may include wildcards. For example  --dhcp-
              mac=set:3com,01:34:23:*:*:*  will set the tag "3com" for any host whose MAC address matches the pattern.

       --dhcp-circuitid=set:<tag>,<circuit-id>, --dhcp-remoteid=set:<tag>,<remote-id>
              Map from RFC3046 relay agent options to tags. This data may be provided by DHCP relay agents.  The  cir-
              cuit-id  or  remote-id  is  normally  given  as  colon-separated 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 tag is set.

              dhcp-remoteid (but not dhcp-circuitid) is supported in IPv6.

       --dhcp-subscrid=set:<tag>,<subscriber-id>
              (IPv4 and IPv6) Map from RFC3993 subscriber-id relay agent options to tags.

       --dhcp-proxy[=<ip addr>]......
              (IPv4 only) A normal DHCP relay agent is only used to forward the initial parts of a DHCP interaction to
              the DHCP server. Once a client is configured, it communicates directly with the server. This is undesir-
              able if the relay agent is addding extra information to the DHCP packets, such as that used by dhcp-cir-
              cuitid and dhcp-remoteid.  A full relay implementation can use the RFC 5107 serverid-override option  to
              force  the  DHCP server to use the relay as a full proxy, with all packets passing through it. This flag
              provides an alternative method of doing the same thing, for relays which don't support RFC  5107.  Given
              alone, it manipulates the server-id for all interactions via relays. If a list of IP addresses is given,
              only interactions via relays at those addresses are affected.

       --dhcp-match=set:<tag>,<option number>|option:<option name>|vi-encap:<enterprise>[,<value>]
              Without a value, set the tag if the client sends a DHCP option of the given number or name. When a value
              is  given,  set  the  tag only if the option is sent and matches the value. The value may be of the form
              "01:ff:*:02" in which case the value must match (apart from widcards)  but  the  option  sent  may  have
              unmatched  data  past  the end of the value. The value may also be of the same form as in dhcp-option in
              which case the option sent is treated as an array, and one element must match, so

              --dhcp-match=set:efi-ia32,option:client-arch,6

              will set the tag "efi-ia32" if the the number 6 appears in the list of architectures sent by the  client
              in option 93. (See RFC 4578 for details.)  If the value is a string, substring matching is used.

              The  special form with vi-encap:<enterpise number> matches against vendor-identifying vendor classes for
              the specified enterprise. Please see RFC 3925 for more details of these rare and interesting beasts.

       --tag-if=set:<tag>[,set:<tag>[,tag:<tag>[,tag:<tag>]]]
              Perform boolean operations on tags. Any tag appearing as set:<tag> is set if all the tags  which  appear
              as  tag:<tag> are set, (or unset when tag:!<tag> is used) If no tag:<tag> appears set:<tag> tags are set
              unconditionally.  Any number of set: and tag: forms  may  appear,  in  any  order.   Tag-if  lines  ares
              executed  in  order,  so if the tag in tag:<tag> is a tag set by another tag-if, the line which sets the
              tag must precede the one which tests it.

       -J, --dhcp-ignore=tag:<tag>[,tag:<tag>]
              When all the given tags appear in the tag set ignore the host and do not allocate it a DHCP lease.

       --dhcp-ignore-names[=tag:<tag>[,tag:<tag>]]
              When all the given tags appear in the tag set, ignore any hostname provided  by  the  host.  Note  that,
              unlike  dhcp-ignore,  it  is permissible to supply no 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.

       --dhcp-generate-names=tag:<tag>[,tag:<tag>]
              (IPv4  only)  Generate  a  name  for DHCP clients which do not otherwise have one, using the MAC address
              expressed in hex, seperated by dashes. Note that if a host provides a name, it will be used  by  prefer-
              ence to this, unless --dhcp-ignore-names is set.

       --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
              (IPv4  only) When all the given tags appear in the tag set, always use broadcast to communicate with the
              host when it is unconfigured. It is permissible to supply no tags, in which case this is  unconditional.
              Most  DHCP  clients which need broadcast replies set a flag in their requests so that this happens auto-
              matically, some old BOOTP clients do not.

       -M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<tftp_servername>]]
              (IPv4 only) 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 dns-
              masq. If dnsmasq is providing a TFTP service (see --enable-tftp ) then only  the  filename  is  required
              here  to  enable network booting.  If the optional tag(s) are given, they must match for this configura-
              tion to be sent.  Instead of an IP address, the TFTP server address can be given as a domain name  which
              is  looked up in /etc/hosts. This name can be associated in /etc/hosts with multiple IP addresses, which
              are used round-robin.  This facility can be used to load balance the tftp load among a set of servers.

       --dhcp-sequential-ip
              Dnsmasq is designed to choose IP addresses for DHCP clients using a hash of the  client's  MAC  address.
              This normally allows a client's address to remain stable long-term, even if the client  sometimes allows
              its DHCP lease to expire. In this default mode IP addresses are  distributed  pseudo-randomly  over  the
              entire available address range. There are sometimes circumstances (typically server deployment) where it
              is more convenient to have IP addresses allocated  sequentially,  starting  from  the  lowest  available
              address,  and setting this flag enables this mode. Note that in the sequential mode, clients which allow
              a lease to expire are much more likely to move IP address; for this reason it should  not  be  generally
              used.

       --pxe-service=[tag:<tag>,]<CSA>,<menu text>[,<basename>|<bootservicetype>][,<server address>|<server_name>]
              Most  uses  of  PXE  boot-ROMS simply allow the PXE system to obtain an IP address and then download the
              file specified by dhcp-boot and execute it. However the PXE system is capable of more complex  functions
              when supported by a suitable DHCP server.

              This specifies a boot option which may appear in a PXE boot menu. <CSA> is client system type, only ser-
              vices of the correct type will appear in a menu. The known  types  are  x86PC,  PC98,  IA64_EFI,  Alpha,
              Arc_x86,  Intel_Lean_Client,  IA32_EFI,  BC_EFI,  Xscale_EFI  and X86-64_EFI; an integer may be used for
              other types. The parameter after the menu text may be a file name, in which case dnsmasq acts as a  boot
              server and directs the PXE client to download the file by TFTP, either from itself ( enable-tftp must be
              set for this to work) or another TFTP server if the final server address/name is given.  Note  that  the
              "layer"  suffix (normally ".0") is supplied by PXE, and should not be added to the basename. If an inte-
              ger boot service type, rather than a basename is given, then the PXE client will search for  a  suitable
              boot  service  for that type on the network. This search may be done by broadcast, or direct to a server
              if its IP address/name is provided.  If no boot service type or filename is provided (or a boot  service
              type  of 0 is specified) then the menu entry will abort the net boot procedure and continue booting from
              local media. The server address can be given as a domain name which is looked  up  in  /etc/hosts.  This
              name can be associated in /etc/hosts with multiple IP addresses, which are used round-robin.

       --pxe-prompt=[tag:<tag>,]<prompt>[,<timeout>]
              Setting  this  provides  a prompt to be displayed after PXE boot. If the timeout is given then after the
              timeout has elapsed with no keyboard input, the first available menu option will be  automatically  exe-
              cuted.  If  the timeout is zero then the first available menu item will be executed immediately. If pxe-
              prompt is ommitted the system will wait for user input if there are multiple items in the menu, but boot
              immediately if there is only one. See pxe-service for details of menu items.

              Dnsmasq  supports  PXE  "proxy-DHCP", in this case another DHCP server on the network is responsible for
              allocating IP addresses, and dnsmasq simply provides the information given in pxe-prompt and pxe-service
              to allow netbooting. This mode is enabled using the proxy keyword in dhcp-range.

       -X, --dhcp-lease-max=<number>
              Limits  dnsmasq  to  the  specified maximum number of DHCP leases. The default is 1000. 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
              (IPv4  only) 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 reacquire a  lease,  if  the
              database is lost.

       --dhcp-alternate-port[=<server port>[,<client port>]]
              (IPv4  only)  Change  the  ports  used for DHCP from the default. If this option is given alone, without
              arguments, it changes the ports used for DHCP from 67 and 68 to 1067 and 1068. If a single  argument  is
              given,  that  port  number  is  used  for  the  server and the port number plus one used for the client.
              Finally, two port numbers allows arbitrary specification of both server and client ports for DHCP.

       -3, --bootp-dynamic[=<network-id>[,<network-id>]]
              (IPv4 only) 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. if this is given without tags, then it unconditionally  enables  dynamic  alloca-
              tion. With tags, only when the tags are all set. It may be repeated with different tag sets.

       -5, --no-ping
              (IPv4  only)  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 tags used to determine them.

       -l, --dhcp-leasefile=<path>
              Use the specified file to store DHCP lease information.

       --dhcp-duid=<enterprise-id>,<uid>
              (IPv6 only) Specify the server persistent UID which the DHCPv6 server will use. This option is not  nor-
              mally  required as dnsmasq creates a DUID automatically when it is first needed. When given, this option
              provides dnsmasq the data required to create a DUID-EN type DUID. Note that once set, the DUID is stored
              in  the  lease database, so to change between DUID-EN and automatically created DUIDs or vice-versa, the
              lease database must be re-intialised. The enterprise-id is assigned by IANA, and the uid is a string  of
              hex octets unique to a particular device.

       -6 --dhcp-script=<path>
              Whenever  a  new  DHCP lease is created, or an old one destroyed, or a TFTP file transfer completes, the
              executable specified by this option is run.  <path> must be an absolute pathname, no PATH search occurs.
              The arguments to the process are "add", "old" or "del", the MAC address of the host (or DUID for IPv6) ,
              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 leasefile-ro is
              set).   If  the  MAC  address  is from a network type other than ethernet, it will have the network type
              prepended, eg "06-01:23:45:67:89:ab" for token ring. 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, with some or all of the following variables
              added

              For both IPv4 and IPv6:

              DNSMASQ_DOMAIN if the fully-qualified domain name of the host is known, this is set to the  domain part.
              (Note that the hostname passed to the script as an argument is never fully-qualified.)

              If the client provides a hostname, DNSMASQ_SUPPLIED_HOSTNAME

              If the client provides user-classes, DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn

              If  dnsmasq  was  compiled  with HAVE_BROKEN_RTC, then the length of the lease (in seconds) is stored in
              DNSMASQ_LEASE_LENGTH, otherwise the time of lease expiry is stored in DNSMASQ_LEASE_EXPIRES. The  number
              of seconds until lease expiry is always stored in DNSMASQ_TIME_REMAINING.

              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.

              DNSMASQ_INTERFACE  stores  the  name  of the interface on which the request arrived; this is not set for
              "old" actions when dnsmasq restarts.

              DNSMASQ_RELAY_ADDRESS is set if the client used a DHCP relay to contact dnsmasq and the  IP  address  of
              the relay is known.

              DNSMASQ_TAGS contains all the tags set during the DHCP transaction, separated by spaces.

              DNSMASQ_LOG_DHCP is set if --log-dhcp is in effect.

              For IPv4 only:

              DNSMASQ_CLIENT_ID if the host provided a client-id.

              If the client provides vendor-class, DNSMASQ_VENDOR_CLASS.

              For IPv6 only:

              If  the client provides vendor-class, DNSMASQ_VENDOR_CLASS_ID, containing the IANA enterprise id for the
              class, and DNSMASQ_VENDOR_CLASS0..DNSMASQ_VENDOR_CLASSn for the data.

              DNSMASQ_SERVER_DUID containing the DUID of the server: this is the same for every call to the script.

              DNSMASQ_IAID containing the IAID for the lease. If the lease is a temporary allocation, this is prefixed
              to 'T'.



              Note  that  the supplied hostname, vendorclass and userclass data is only  supplied for "add" actions or
              "old" actions when a host resumes an existing lease, since these data are not held  in  dnsmasq's  lease
              database.



              All  file  descriptors are closed except stdin, stdout and stderr which are open to /dev/null (except in
              debug mode).

              The script is not invoked concurrently: at most one instance of the  script  is  ever  running  (dnsmasq
              waits  for  an  instance  of  script to exit before running the next). Changes to the lease database are
              which require the script to be invoked are queued awaiting exit of a running instance.  If this queueing
              allows  multiple  state changes occur to a single lease before the script can be run then earlier states
              are discarded and the current state of that lease is reflected when the script finally runs.

              At dnsmasq 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". When dnsmasq receives a HUP sig-
              nal, the script will be invoked for existing leases with an "old " event.


              There are two further actions which may appear as the first argument to the script, "init"  and  "tftp".
              More  may  be  added  in  the  future, so scripts should be written to ignore unknown actions. "init" is
              described below in --leasefile-ro The "tftp" action is invoked when a TFTP file transfer completes:  the
              arguments  are the file size in bytes, the address to which the file was sent, and the complete pathname
              of the file.


       --dhcp-luascript=<path>
              Specify a script written in Lua, to be run when leases are created, destroyed or changed.  To  use  this
              option,  dnsmasq must be compiled with the correct support. The Lua interpreter is intialised once, when
              dnsmasq starts, so that global variables persist between lease events. The Lua code must define a  lease
              function,  and may provide init and shutdown functions, which are called, without arguments when dnsmasq
              starts up and terminates. It may also provide a tftp function.

              The lease function receives the information detailed in --dhcp-script.  It gets two  arguments,  firstly
              the  action,  which  is  a  string  containing, "add", "old" or "del", and secondly a table of tag value
              pairs. The tags mostly correspond to the environment variables detailed  above,  for  instance  the  tag
              "domain"  holds  the  same  data  as the environment variable DNSMASQ_DOMAIN. There are a few extra tags
              which hold the data supplied as arguments to --dhcp-script.  These are mac_address, ip_address and host-
              name for IPv4, and client_duid, ip_address and hostname for IPv6.

              The tftp function is called in the same way as the lease function, and the table holds the tags destina-
              tion_address, file_name and file_size.

       --dhcp-scriptuser
              Specify the user as which to run the lease-change script or Lua script. This defaults to root,  but  can
              be changed to another user using this flag.

       -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 <inter-
              face>. This option is necessary when using "old style" bridging on BSD platforms, since  packets  arrive
              at tap interfaces which don't have an IP address.

       -s, --domain=<domain>[,<address range>[,local]]
              Specifies  DNS  domains  for  the  DHCP  server. Domains may be be given unconditionally (without the IP
              range) or for limited IP ranges. 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-config-
              ured 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 suf-
              fix  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).

              The address range can be of the form <ip address>,<ip address> or <ip address>/<netmask> or just a  sin-
              gle <ip address>. See --dhcp-fqdn which can change the behaviour of dnsmasq with domains.

              If the address range is given as ip-address/network-size, then a additional flag "local" may be supplied
              which has the  effect  of  adding  --local  declarations  for  forward  and  reverse  DNS  queries.  Eg.
              --domain=thekelleys.org.uk,192.168.0.0/24,local       is       identical       to       --domain=thekel-
              leys.org.uk,192.168.0.0/24 --local=/thekelleys.org.uk/ --local=/0.168.192.in-addr.arpa/ The network size
              must be 8, 16 or 24 for this to be legal.

       --dhcp-fqdn
              In  the  default mode, dnsmasq inserts the unqualified names of DHCP clients into the DNS. For this rea-
              son, the names must be unique, even if two clients which have the same name are in different domains. If
              a  second  DHCP  client appears which has the same name as an existing client, the name is transfered to
              the new client. If --dhcp-fqdn is set, this behaviour changes: the unqualified name is no longer put  in
              the  DNS,  only the qualified name. Two DHCP clients with the same name may both keep the name, provided
              that the domain part is different (ie the fully qualified names differ.) To ensure that all names have a
              domain part, there must be at least --domain without an address specified when --dhcp-fqdn is set.

       --dhcp-client-update
              Normally,  when  giving  a  DHCP  lease, dnsmasq sets flags in the FQDN option to tell the client not to
              attempt a DDNS update with its name and IP address. This is because the name-IP  pair  is  automatically
              added  into  dnsmasq's  DNS  view. This flag suppresses that behaviour, this is useful, for instance, to
              allow Windows clients to update Active Directory servers. See RFC 4702 for details.

       --enable-ra
              Enable dnsmasq's IPv6 Router Advertisement feature. DHCPv6 doesn't handle complete network configuration
              in  the same way as DHCPv4. Router discovery and (possibly) prefix discovery for autonomous address cre-
              ation are handled by a different protocol. When DHCP is in use, only a subset of  this  is  needed,  and
              dnsmasq  can handle it, using existing DHCP configuration to provide most data. When RA is enabled, dns-
              masq will advertise a prefix for each dhcp-range, with default router and recursive DNS  server  as  the
              relevant  link-local  address  on the machine running dnsmasq. By default, he "managed address" bits are
              set, and the "use SLAAC" bit is reset. This can be changed for individual subnets with the mode keywords
              described  in  --dhcp-range.  RFC6106 DNS parameters are included in the advertisements. By default, the
              relevant link-local address of the machine running dnsmasq is sent as recursive DNS server. If provided,
              the DHCPv6 options dns-server and domain-search are used for RDNSS and DNSSL.

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

       --tftp-root=<directory>[,<interface>]
              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. If the optional interface argument
              is given, the directory is only used for TFTP requests via that interface.

       --tftp-unique-root
              Add the IP address of the TFTP client as a path component on the end of the TFTP-root (in standard  dot-
              ted-quad  format). Only valid if a tftp-root is set and the directory exists. For instance, if tftp-root
              is  "/tftp"  and  client  1.2.3.4  requests  file   "myfile"   then   the   effective   path   will   be
              "/tftp/1.2.3.4/myfile" if /tftp/1.2.3.4 exists or /tftp/myfile otherwise.

       --tftp-secure
              Enable  TFTP  secure  mode: without this, any file which is readable by the dnsmasq process 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-lowercase
              Convert filenames in TFTP requests to all lowercase. This is useful for requests from Windows  machines,
              which  have  case-insensitive  filesystems and tend to play fast-and-loose with case in filenames.  Note
              that dnsmasq's tftp server always converts "\" to "/" in filenames.

       --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 connection 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
              descriptors, serving different files simultaneously to n clients will require about (2*n) + 10  descrip-
              tors. If --tftp-port-range is given, that can affect the number of concurrent connections.

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

       --tftp-port-range=<start>,<end>
              A TFTP server listens on a well-known port (69) for connection initiation, but it also  uses  a  dynami-
              cally-allocated port for each connection. Normally these are allocated by the OS, but this option speci-
              fies a range of ports for use by TFTP transfers. This can be useful when TFTP has to  traverse  a  fire-
              wall.  The start of the range cannot be lower than 1025 unless dnsmasq is running as root. The number of
              concurrent TFTP connections is limited by the size of the port range.

       -C, --conf-file=<file>
              Specify a different configuration file. The conf-file option is also allowed in configuration files,  to
              include multiple configuration files. A filename of "-" causes dnsmasq to read configuration from stdin.

       -7, --conf-dir=<directory>[,<file-extension>......]
              Read all the files in the given directory as configuration files. If extension(s) are given,  any  files
              which  end  in those extensions are skipped. Any files whose names end in ~ or start with . or start and
              end with # are always 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 consists 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.
       Quoting is allowed in a config file: between " quotes the special meanings of ,:. and #  are  removed  and  the
       following  escapes  are  allowed:  \\ \" \t \e \b \r and \n. The later corresponding to tab, escape, backspace,
       return and newline.

NOTES
       When it receives a SIGHUP, dnsmasq clears its cache and then re-loads /etc/hosts and /etc/ethers and  any  file
       given  by  --dhcp-hostsfile,  --dhcp-optsfile  or --addn-hosts.  The dhcp lease change script is called for all
       existing DHCP leases. 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 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. For each upstream server it gives the number
       of queries sent, and the number which resulted in an error. In --no-daemon mode or when full logging is enabled
       (-q), a complete dump of the contents of the cache is made.

       When it receives SIGUSR2 and it is logging direct to a file (see --log-facility ) dnsmasq will close and reopen
       the log file. Note that during this operation, dnsmasq will not be running as root. When it first  creates  the
       logfile dnsmasq changes the ownership of the file to the non-root user it will run as. Logrotate should be con-
       figured to create a new log file with the ownership which matches the existing one before sending SIGUSR2.   If
       TCP  DNS  queries  are  in progress, the old logfile will remain open in child processes which are handling TCP
       queries and may continue to be written. There is a limit of 150 seconds, after which all existing TCP processes
       will  have  expired:  for  this reason, it is not wise to configure logfile compression for logfiles which have
       just been rotated. Using logrotate, the required options are create and delaycompress.



       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  specifi-
       cations optionally take a domain name which tells dnsmasq to use that server only to find names in that partic-
       ular 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.

       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  tag  system works as follows: For each DHCP request, dnsmasq collects a set of valid tags from active con-
       figuration lines which include set:<tag>, including one from the dhcp-range used to allocate the  address,  one
       from any matching dhcp-host (and "known" if a dhcp-host matches) The tag "bootp" is set for BOOTP requests, and
       a tag whose name is the name of the interface on which the request arrived is also set.

       Any configuration lines which includes one or more tag:<tag> contructs will only be valid if all that tags  are
       matched  in  the  set derived above. Typically this is dhcp-option.  dhcp-option which has 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=tag:!purple,3,1.2.3.4 sends the option
       when the tag purple is not in the set of valid tags. (If using this in a command line rather than a  configura-
       tion file, be sure to escape !, which is a shell metacharacter)

       When  selecting  dhcp-options, a tag from dhcp-range is second class relative to other tags, to make it easy to
       override options for individual hosts, so dhcp-range=set:interface1,......   dhcp-host=set:myhost,.....   dhcp-
       option=tag:interface1,option:nis-domain,"domain1"  dhcp-option=tag:myhost,option:nis-domain,"domain2"  will set
       the NIS-domain to domain1 for hosts in the range, but override that to domain2 for a particular host.


       Note that for dhcp-range both tag:<tag> and set:<tag> are allowed, to both select the range  in  use  based  on
       (eg) dhcp-host, and to affect the options sent, based on the range selected.

       This system evolved from an earlier, more limited one and for backward compatibility "net:" may be used instead
       of "tag:" and "set:" may be omitted. (Except in dhcp-host, where "net:" may be used instead of "set:".) For the
       same reason, '#' may be used instead of '!' to indicate NOT.

       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 mappings.) The filename parameter in a BOOTP request is used as a tag, as  is  the  tag
       "bootp", allowing some control over the options returned to different classes of hosts.


EXIT CODES
       0 - Dnsmasq successfully forked into the background, or terminated normally if backgrounding is not enabled.

       1 - A problem with configuration was detected.

       2  -  A  problem  with network access occurred (address in use, attempt to use privileged ports without permis-
       sion).

       3 - A problem occurred with a filesystem operation (missing file/directory, permissions).

       4 - Memory allocation failure.

       5 - Other miscellaneous problem.

       11 or greater - a non zero return code was received from the lease-script process "init" call.  The  exit  code
       from dnsmasq is the script's exit code with 10 added.


LIMITS
       The  default  values  for  resource  limits in dnsmasq are generally conservative, and appropriate for embedded
       router type devices with slow processors and limited memory. On  more  capable  hardware,  it  is  possible  to
       increase  the limits, and handle many more clients. The following 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. The DHCP 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 num-
       bers 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 resolv-
       ing 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.


INTERNATIONALISATION
       Dnsmasq  can be compiled to support internationalisation. To do this, the make targets "all-i18n" and "install-
       i18n" should be used instead of the standard targets "all" and "install". When internationalisation is compiled
       in,  dnsmasq  will produce log messages in the local language and support internationalised domain names (IDN).
       Domain names in /etc/hosts, /etc/ethers and /etc/dnsmasq.conf which contain non-ASCII characters will be trans-
       lated  to the DNS-internal punycode representation. Note that dnsmasq determines both the language for messages
       and the assumed charset for configuration files from the LANG environment variable. This should be set  to  the
       system  default  value  by the script which is responsible for starting dnsmasq. When editing the configuration
       files, be careful to do so using only the system-default locale and not user-specific one, since dnsmasq has no
       direct way of determining the charset in use, and must assume that it is the system default.


FILES
       /etc/dnsmasq.conf

       /usr/local/etc/dnsmasq.conf

       /etc/resolv.conf /var/run/dnsmasq/resolv.conf /etc/ppp/resolv.conf /etc/dhcpc/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 <simonATthekelleys.uk>.





                                                                    DNSMASQ(8)