Provided by: dnsmasq-base_2.59-4_amd64 bug

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 DNS and TFTP, but not DHCP.

OPTIONS

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

       --test Read and syntax check configuration file(s). Exit with code 0 if all is  OK,  or  a
              non-zero code otherwise. 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 requestor 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 dnsmasq is run under daemontools or launchd.

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

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

       -8, --log-facility=<facility>
              Set  the  facility  to  which  dnsmasq  will  send syslog entries, this defaults to
              DAEMON, and to LOCAL0 when debug mode  is  in  operation.  If  the  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-interface
              options, use --listen-address instead.

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

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

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

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

       -y, --localise-queries
              Return answers to DNS queries from /etc/hosts which depend on  the  interface  over
              which  the  query  was  received. If a name in /etc/hosts has more than one address
              associated with it, and at least one of those addresses is on the  same  subnet  as
              the interface to which the query was sent, then return only the address(es) on that
              subnet. This allows  for  a  server   to  have  multiple  addresses  in  /etc/hosts
              corresponding  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 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,  subsequent
              ones  add  to  the  list.  This  is  only  allowed  when polling; the file with the
              currently latest modification time is the one used.

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

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

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

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

       -A, --address=/<domain>/[domain/]<ipaddr>
              Specify an IP address to return for any host in the given domains.  Queries in  the
              domains  are  never  forwarded  and always replied to with the specified IP address
              which may be IPv4 or IPv6. To give both IPv4 and IPv6 addresses for a  domain,  use
              repeated  -A  flags.   Note  that  /etc/hosts  and  DHCP  leases  override this for
              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.

       -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) or from DHCP. 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.

       --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 validation and set a bit in the reply if it
              succeeds.  Dnsmasq  is  not a DNSSEC validator, so it cannot perform 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  conntrack
              support  compiled  in  and  the  kernel  must  have  conntrack support included and
              configured. This option cannot be combined with --query-port.

       -F,       --dhcp-range=[interface:<interface>,][tag:<tag>[,tag:<tag>],][set:<tag],]<start-
       addr>,<end-addr>[,<netmask>[,<broadcast>]][,<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.
              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.

              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 end address  may  be
              replaced  by  the keyword static which tells dnsmasq to enable DHCP for the network
              specified, but not to dynamically allocate IP  addresses:  only  hosts  which  have
              static  addresses  given  via dhcp-host or from /etc/ethers will be served. The end
              address may be replaced by the keyword proxy in which  case  dnsmasq  will  provide
              proxy-DHCP on the specified subnet. (See pxe-prompt and pxe-service for details.)

              The  interface:<interface name> section is not normally used. See the NOTES section
              for details of this.

       -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 ommit the hardware address and
              include the hostname, in which case the IP address and lease times  will  apply  to
              any      machine      claiming      that      name.     For     example     --dhcp-
              host=00:20:e0:3b:13:af,wap,infinite tells dnsmasq to give the machine with hardware
              address  00:20:e0:3b:13:af  the  name  wap,  and  an  infinite DHCP lease.  --dhcp-
              host=lap,192.168.0.199 tells dnsmasq to always allocate  the  machine  lap  the  IP
              address 192.168.0.199.

              Addresses  allocated  like this are not constrained to be in the range given by the
              --dhcp-range option, but they must be 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:clientidastext,.....

              The  special  option  id:* means "ignore any client-id and use MAC addresses only."
              This is useful when a client presents a client-id sometimes but not others.

              If a name appears in /etc/hosts, the associated address can be allocated to a  DHCP
              lease,  but  only if a --dhcp-host option 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 single 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, 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 dnsmasq 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 dnsmasq
              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 hardware address, followed by either a hostname or dotted-quad  IP
              address.  When  read by dnsmasq these lines have exactly the same effect as --dhcp-
              host options containing the same information. /etc/ethers is re-read  when  dnsmasq
              receives SIGHUP.

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

              Be careful: no checking is done that the correct type of data for the option number
              is sent, it is quite possible to persuade dnsmasq to generate illegal DHCP  packets
              with injudicious use of this flag. When the value is a decimal number, dnsmasq must
              determine how large the data item is. It does this by examining the  option  number
              and/or  the  value,  but  can  be  overridden  by appending a single letter flag as
              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  using  --dhcp-option:  for
              instance  --dhcp-option=vendor:PXEClient,1,0.0.0.0  sends  the  encapsulated vendor
              class-specific option  "mftp-address=0.0.0.0"  to  any  client  whose  vendor-class
              matches  "PXEClient".  The  vendor-class  matching  is substring based (see --dhcp-
              vendorclass for details). If a vendor-class option (number 60) is sent by  dnsmasq,
              then  that  is used for selecting encapsulated options in preference to any sent by
              the  client.  It  is  possible  to  omit  the   vendorclass   completely;   --dhcp-
              option=vendor:,1,0.0.0.0 in which case the encapsulated option is always sent.

              Options   may   be   encapsulated   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.

              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
              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, confuse old or broken clients.  This  flag
              forces "simple and safe" behaviour to avoid problems in such a case.

       -U, --dhcp-vendorclass=set:<tag>,<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:printers,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.

       -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>
              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 circuit-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-subscrid=set:<tag>,<subscriber-id>
              Map from RFC3993 subscriber-id relay agent options to tags.

       --dhcp-proxy[=<ip addr>]......
              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 undesirable if the relay agent is  addding  extra
              information  to  the  DHCP  packets,  such as that used by dhcp-circuitid 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>]
              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 preference to this, unless --dhcp-ignore-names is set.

       --dhcp-broadcast[=tag:<tag>[,tag:<tag>]]
              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  automatically,  some  old  BOOTP
              clients do not.

       -M, --dhcp-boot=[tag:<tag>,]<filename>,[<servername>[,<server address>|<tftp_servername>]]
              Set  BOOTP  options  to be returned by the DHCP server. Server name and address are
              optional: if not provided, the name is left empty,  and  the  address  set  to  the
              address of the machine running dnsmasq. If dnsmasq is providing a TFTP service (see
              --enable-tftp ) then only the filename is required here to enable network  booting.
              If  the  optional  tag(s)  are  given, they must match for this configuration 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>]
              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 services 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 IP address is given.   Note  that  the  "layer"  suffix  (normally  ".0")  is
              supplied  by  PXE,  and  should  not  be  added to the basename. If an integer 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 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.

       --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 executed. 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
              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>]]
              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>]]
              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 allocation. With tags, only when the
              tags are all set. It may be repeated with different tag sets.

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

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

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

       -6 --dhcp-script=<path>
              Whenever  a  new  DHCP  lease  is  created, or an old one destroyed, 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, 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.

              DNSMASQ_CLIENT_ID if the host provided a client-id.

              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 vendor-class, hostname or user-class, these are provided  in
              DNSMASQ_VENDOR_CLASS                  DNSMASQ_SUPPLIED_HOSTNAME                 and
              DNSMASQ_USER_CLASS0..DNSMASQ_USER_CLASSn variables, but only for "add"  actions  or
              "old"  actions when a host resumes an existing lease, since these data are not held
              in dnsmasq's lease database.

              If dnsmasq was compiled with HAVE_BROKEN_RTC, then the  length  of  the  lease  (in
              seconds)  is  stored in 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.

              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 signal, the script will be invoked for existing
              leases with an "old " event.

       --dhcp-scriptuser
              Specify the user as which to run the lease-change 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 <interface>. 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-configured hosts to claim.
              The intention is to constrain hostnames so that an untrusted host on the LAN cannot
              advertise  its  name via dhcp as e.g. "microsoft.com" and capture traffic not meant
              for it. If no domain suffix is specified, then any DHCP hostname with a domain part
              (ie  with  a  period)  will  be disallowed and logged. If suffix is specified, then
              hostnames with a domain part are allowed, provided  the  domain  part  matches  the
              suffix. In addition, when a suffix is set then hostnames without a domain part have
              the suffix added  as  an  optional  domain  part.  Eg  on  my  network  I  can  set
              --domain=thekelleys.org.uk  and have a machine whose DHCP hostname is "laptop". The
              IP address for that  machine  is  available  from  dnsmasq  both  as  "laptop"  and
              "laptop.thekelleys.org.uk".  If  the domain is given as "#" then the domain is read
              from the first "search" directive in /etc/resolv.conf (or equivalent).

              The  address  range  can  be  of  the  form  <ip  address>,<ip  address>   or   <ip
              address>/<netmask>  or just a single <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=thekelleys.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 reason, 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.

       --enable-tftp[=<interface>]
              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). See NOTES section for use of the
              interface argument.

       --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 dotted-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-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 descriptors. 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  dynamically-allocated  port  for each connection. Normally these are
              allocated by the OS, but this option specifies a range of ports  for  use  by  TFTP
              transfers.  This  can  be useful when TFTP has to traverse a firewall. 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 configured 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 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.

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

       dhcp-range  may  have  an  interface  name  supplied  as "interface:<interface-name>". The
       semantics if this are as follows: For DHCP, if any other dhcp-range  exists  _without_  an
       interface  name,  then  the  interface  name  is ignored and and dnsmasq behaves as if the
       interface parts did not exist, otherwise DHCP is only provided to interfaces mentioned  in
       dhcp-range  declarations.  For DNS, if there are no --interface or --listen-address flags,
       behaviour is unchanged by the interface part. If either of these flags  are  present,  the
       interfaces mentioned in dhcp-ranges are added to the set which get DNS service.

       Similarly,  enable-tftp  may  take  an  interface  name,  which  enables  TFTP  only for a
       particular interface, ignoring --interface or --listen-address flags. In addition  --tftp-
       secure  and  --tftp-unique-root and --tftp-no-blocksize are ignored for requests from such
       interfaces. (A --tftp-root directive giving  a  root  path  and  an  interface  should  be
       provided too.)

       These rules may seem odd at first sight, but  they allow a single line  of the form "dhcp-
       range=interface:virt0,192.168.0.4,192.168.0.200" to  be  added  to  dnsmasq  configuration
       which  then  supplies  DHCP  and  DNS  services  to that interface, without affecting what
       services are supplied to other interfaces and irrespective of the  existance  or  lack  of
       "interface=<interface>" lines elsewhere in the dnsmasq configuration.  "enable-tftp=virt0"
       and "tftp-root=<root>,virt0" do the same job for TFTP.
        The idea is that such a line can be added automatically by libvirt or equivalent systems,
       without disturbing any manual configuration.

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

       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 numbers of file handles. If the limit is set too
       high using --tftp-max it will be scaled down and the actual limit logged at start-up. Note
       that  more transfers are possible when the same file is being sent than when each transfer
       sends a different file.

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

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
       translated 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 <simon@thekelleys.org.uk>.

                                                                                       DNSMASQ(8)