diff options
Diffstat (limited to 'man/dnsmasq.8')
| -rwxr-xr-x | man/dnsmasq.8 | 1290 |
1 files changed, 1290 insertions, 0 deletions
diff --git a/man/dnsmasq.8 b/man/dnsmasq.8 new file mode 100755 index 0000000..a5eac63 --- /dev/null +++ b/man/dnsmasq.8 @@ -0,0 +1,1290 @@ +.TH DNSMASQ 8 +.SH NAME +dnsmasq \- A lightweight DHCP and caching DNS server. +.SH SYNOPSIS +.B dnsmasq +.I [OPTION]... +.SH "DESCRIPTION" +.BR dnsmasq +is a lightweight DNS, TFTP and DHCP server. It is intended to provide +coupled DNS and DHCP service to a LAN. +.PP +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. +.PP +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. +.PP +Dnsmasq +supports IPv6 for DNS, but not DHCP. +.SH 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. +.TP +.B --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. +.TP +.B \-h, --no-hosts +Don't read the hostnames in /etc/hosts. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B --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. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-q, --log-queries +Log the results of DNS queries handled by dnsmasq. Enable a full cache dump on receipt of SIGUSR1. +.TP +.B \-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. (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. +.TP +.B --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. +.TP +.B \-x, --pid-file=<path> +Specify an alternate path for dnsmasq to record its process-id in. Normally /var/run/dnsmasq.pid. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-v, --version +Print the version number. +.TP +.B \-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. +.TP +.B \-P, --edns-packet-max=<size> +Specify the largest EDNS.0 UDP packet which is supported by the DNS +forwarder. Defaults to 1280, which is the RFC2671-recommended maximum +for ethernet. +.TP +.B \-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. +.TP +.B --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. +.TP +.B \-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 +.B \--interface +option is used. If no +.B \--interface +or +.B \--listen-address +options are given dnsmasq listens on all available interfaces except any +given in +.B \--except-interface +options. IP alias interfaces (eg "eth1:0") cannot be used with +.B --interface +or +.B --except-interface +options, use --listen-address instead. +.TP +.B \-I, --except-interface=<interface name> +Do not listen on the specified interface. Note that the order of +.B \--listen-address +.B --interface +and +.B --except-interface +options does not matter and that +.B --except-interface +options always override the others. +.TP +.B \-2, --no-dhcp-interface=<interface name> +Do not provide DHCP or TFTP on the specified interface, but do provide DNS service. +.TP +.B \-a, --listen-address=<ipaddr> +Listen on the given IP address(es). Both +.B \--interface +and +.B \--listen-address +options may be given, in which case the set of both interfaces and +addresses is used. Note that if no +.B \--interface +option is given, but +.B \--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 +.B \--listen-address +option. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-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 +.B --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 +.B --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 +.TP +.B \-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 +.TP +.B \-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. +.TP +.B \-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 +.BR 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. +.TP +.B \-R, --no-resolv +Don't read /etc/resolv.conf. Get upstream servers only from the command +line or the dnsmasq configuration file. +.TP +.B \-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. +.TP +.B \-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 +.TP +.B --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. +.TP +.B --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. +.TP +.B \-n, --no-poll +Don't poll /etc/resolv.conf for changes. +.TP +.B --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. +.TP +.B \-D, --domain-needed +Tells dnsmasq to never forward queries for plain names, without dots +or domain parts, to upstream nameservers. If the name is not known +from /etc/hosts or DHCP then a "not found" answer is returned. +.TP +.B \-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 +.B -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, +.B // +has the special meaning of "unqualified names only" ie names without any +dots in them. A non-standard port may be specified as +part of the IP +address using a # character. +More than one -S flag is allowed, with +repeated domain or ipaddr parts as required. + +Also permitted is a -S +flag which gives a domain but no IP address; this tells dnsmasq that +a domain is local and it may answer queries from /etc/hosts or DHCP +but should never forward queries on that domain to any upstream +servers. +.B local +is a synonym for +.B server +to make configuration files clearer in this case. + +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. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-e, --selfmx +Return an MX record pointing to itself for each local +machine. Local machines are those in /etc/hosts or with DHCP leases. +.TP +.B \-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. +.TP +.B \-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 +.B --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. +.TP +.B \-Y, --txt-record=<name>[[,<text>],<text>] +Return a TXT DNS record. The value of TXT record is a set of strings, +so any number may be included, split by commas. +.TP +.B --ptr-record=<name>[,<target>] +Return a PTR DNS record. +.TP +.B --naptr-record=<name>,<order>,<preference>,<flags>,<service>,<regexp>[,<replacement>] +Return an NAPTR DNS record, as specified in RFC3403. +.TP +.B --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. +.TP +.B --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. +.TP +.B \-c, --cache-size=<cachesize> +Set the size of dnsmasq's cache. The default is 150 names. Setting the cache size to zero disables caching. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B \-F, --dhcp-range=[[net:]network-id,]<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 +.B 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. It is, however, required for networks which +receive DHCP service via a relay agent. The broadcast address is +always optional. It is always +allowed to have more than one dhcp-range in a single subnet. The optional +network-id is a alphanumeric label which marks this network so that +dhcp options may be specified on a per-network basis. +When it is prefixed with 'net:' then its meaning changes from setting +a tag to matching it. Only one tag may be set, but more than one tag may be matched. +The end address may be replaced by the keyword +.B 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 +.B dhcp-host +or from /etc/ethers will be served. The end address may be replaced by +the keyword +.B proxy +in which case dnsmasq will provide proxy-DHCP on the specified +subnet. (See +.B pxe-prompt +and +.B pxe-service +for details.) +.TP +.B \-G, --dhcp-host=[<hwaddr>][,id:<client_id>|*][,net:<netid>][,<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 +.B --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. +.B --dhcp-host=lap,192.168.0.199 +tells +dnsmasq to always allocate the machine lap the IP address +192.168.0.199. Addresses allocated like this are not constrained to be +in the range given by the --dhcp-range option, but they must be on the +network being served by the DHCP server. It is allowed to use client identifiers rather than +hardware addresses to identify hosts by prefixing with 'id:'. Thus: +.B --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: +.B --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 +.B --dhcp-host +option specifying the name also exists. The special keyword "ignore" +tells dnsmasq to never offer a DHCP lease to a machine. The machine +can be specified by hardware address, client ID or hostname, for +instance +.B --dhcp-host=00:20:e0:3b:13:af,ignore +This is +useful when there is another DHCP server on the network which should +be used by some machines. + +The net:<network-id> sets the network-id tag +whenever this dhcp-host directive is in use. This can be used to +selectively send DHCP options just for this host. When a host matches any +dhcp-host directive (or one implied by /etc/ethers) then the special +network-id tag "known" is set. This allows dnsmasq to be configured to +ignore requests from unknown machines using +.B --dhcp-ignore=#known +Ethernet addresses (but not client-ids) may have +wildcard bytes, so for example +.B --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 +.B --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: +.B --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. +.TP +.B --dhcp-hostsfile=<file> +Read DHCP host information from the specified file. 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. +.TP +.B --dhcp-optsfile=<file> +Read DHCP option information from the specified file. 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 +.B --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. +.TP +.B \-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 +.B --dhcp-host +options containing the same information. /etc/ethers is re-read when +dnsmasq receives SIGHUP. +.TP +.B \-O, --dhcp-option=[<network-id>,[<network-id>,]][encap:<opt>,][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 +.B --dhcp-option=3,192.168.4.4 +or +.B --dhcp-option = option:router, 192.168.4.4 +and to set the time-server address to 192.168.0.4, do +.B --dhcp-option = 42,192.168.0.4 +or +.B --dhcp-option = option:ntp-server, 192.168.0.4 +The special address 0.0.0.0 is taken to mean "the address of the +machine running dnsmasq". Data types allowed are comma separated +dotted-quad IP addresses, a decimal number, colon-separated hex digits +and a text string. If the optional network-ids are given then +this option is only sent when all the network-ids are matched. + +Special processing is done on a text argument for option 119, to +conform with RFC 3397. Text or dotted-quad IP addresses as arguments +to option 120 are handled as per RFC 3361. Dotted-quad IP addresses +which are followed by a slash and then a netmask size are encoded as +described in RFC 3442. + +Be careful: no checking is done that the correct type of data for the +option number is sent, it is quite possible to +persuade dnsmasq to generate illegal DHCP packets with injudicious use +of this flag. When the value is a decimal number, dnsmasq must determine how +large the data item is. It does this by examining the option number and/or the +value, but can be overridden by appending a single letter flag as 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 +.B --dhcp-option=66,"1.2.3.4" + +Encapsulated Vendor-class options may also be specified using +--dhcp-option: for instance +.B --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; +.B --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 +.B --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 address 0.0.0.0 is not treated specially in +encapsulated options. +.TP +.B --dhcp-option-force=[<network-id>,[<network-id>,]][encap:<opt>,][vendor:[<vendor-class>],]<opt>,[<value>[,<value>]] +This works in exactly the same way as +.B --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. +.TP +.B --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. +.TP +.B \-U, --dhcp-vendorclass=<network-id>,<vendor-class> +Map from a vendor-class string to a network id tag. Most DHCP clients provide a +"vendor class" which represents, in some sense, the type of host. This option +maps vendor classes to tags, so that DHCP options may be selectively delivered +to different classes of hosts. For example +.B dhcp-vendorclass=printers,Hewlett-Packard JetDirect +will allow options to be set only for HP printers like so: +.B --dhcp-option=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. +.TP +.B \-j, --dhcp-userclass=<network-id>,<user-class> +Map from a user-class string to a network id 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". +.TP +.B \-4, --dhcp-mac=<network-id>,<MAC address> +Map from a MAC address to a network-id tag. The MAC address may include +wildcards. For example +.B --dhcp-mac=3com,01:34:23:*:*:* +will set the tag "3com" for any host whose MAC address matches the pattern. +.TP +.B --dhcp-circuitid=<network-id>,<circuit-id>, --dhcp-remoteid=<network-id>,<remote-id> +Map from RFC3046 relay agent options to network-id tags. This data may +be provided by DHCP relay agents. The circuit-id or remote-id is +normally given as colon-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 network-id tag is set. +.TP +.B --dhcp-subscrid=<network-id>,<subscriber-id> +Map from RFC3993 subscriber-id relay agent options to network-id tags. +.TP +.B --dhcp-match=<network-id>,<option number>|option:<option name>[,<value>] +Without a value, set the network-id 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 +.B dhcp-option +in which case the option sent is treated as an array, and one element +must match, so + +--dhcp-match=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. +.TP +.B \-J, --dhcp-ignore=<network-id>[,<network-id>] +When all the given network-ids match the set of network-ids derived +from the net, host, vendor and user classes, ignore the host and do +not allocate it a DHCP lease. +.TP +.B --dhcp-ignore-names[=<network-id>[,<network-id>]] +When all the given network-ids match the set of network-ids derived +from the net, host, vendor and user classes, ignore any hostname +provided by the host. Note that, unlike dhcp-ignore, it is permissible +to supply no netid tags, in which case DHCP-client supplied hostnames +are always ignored, and DHCP hosts are added to the DNS using only +dhcp-host configuration in dnsmasq and the contents of /etc/hosts and +/etc/ethers. +.TP +.B --dhcp-broadcast=<network-id>[,<network-id>] +When all the given network-ids match the set of network-ids derived +from the net, host, vendor and user classes, always use broadcast to +communicate with the host when it is unconfigured. Most DHCP clients which +need broadcast replies set a flag in their requests so that this +happens automatically, some old BOOTP clients do not. +.TP +.B \-M, --dhcp-boot=[net:<network-id>,]<filename>,[<servername>[,<server address>]] +Set BOOTP options to be returned by the DHCP server. Server name and +address are optional: if not provided, the name is left empty, and the +address set to the address of the machine running dnsmasq. If dnsmasq +is providing a TFTP service (see +.B --enable-tftp +) then only the filename is required here to enable network booting. +If the optional network-id(s) are given, +they must match for this configuration to be sent. Note that +network-ids are prefixed by "net:" to distinguish them. +.TP +.B --pxe-service=[net:<network-id>,]<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 +.B 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 ( +.B 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 multicast or broadcast, or direct to a server if its IP address is provided. A boot service +type of 0 is special, and will abort the net boot procedure and +continue booting from local media. +.TP +.B --pxe-prompt=[net:<network-id>,]<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 +.B 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 +.B 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 +.B pxe-prompt +and +.B pxe-service +to allow netbooting. This mode is enabled using the +.B proxy +keyword in +.B dhcp-range. +.TP +.B \-X, --dhcp-lease-max=<number> +Limits dnsmasq to the specified maximum number of DHCP leases. The +default is 150. This limit is to prevent DoS attacks from hosts which +create thousands of leases and use lots of memory in the dnsmasq +process. +.TP +.B \-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. +.TP +.B --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. +.TP +.B \-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. +.TP +.B \-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. +.TP +.B --log-dhcp +Extra logging for DHCP: log all the options sent to DHCP clients and +the netid tags used to determine them. +.TP +.B \-l, --dhcp-leasefile=<path> +Use the specified file to store DHCP lease information. +.TP +.B \-6 --dhcp-script=<path> +Whenever a new DHCP lease is created, or an old one destroyed, the +executable specified by this option is run. 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, and if the +host provided a client-id, this is stored in the environment variable +DNSMASQ_CLIENT_ID. If the fully-qualified domain name of the host is +known, the domain part is stored in DNSMASQ_DOMAIN. +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. +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: if subsequent lease +changes occur, the script is not invoked again until any existing +invocation exits. 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". <path> +must be an absolute pathname, no PATH search occurs. When dnsmasq +receives a HUP signal, the script will be invoked for existing leases +with an "old " event. +.TP +.B --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. +.TP +.B \-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 +.B --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. +.TP +.B --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. +.TP +.B \-s, --domain=<domain>[,<address range>] +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 +.B --domain=thekelleys.org.uk +and have a machine whose DHCP hostname is "laptop". The IP address for that machine is available from +.B 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 +.B --dhcp-fqdn +which can change the behaviour of dnsmasq with domains. +.TP +.B --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 +.B --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 +.B --domain +without an address specified when +.B --dhcp-fqdn +is set. +.TP +.B --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). +.TP +.B --tftp-root=<directory> +Look for files to transfer using TFTP relative to the given +directory. When this is set, TFTP paths which include ".." are +rejected, to stop clients getting outside the specified root. +Absolute paths (starting with /) are allowed, but they must be within +the tftp-root. +.TP +.B --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. +.TP +.B --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. +.TP +.B --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 +.B --tftp-port-range +is given, that can affect the number of concurrent connections. +.TP +.B --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. +.TP +.B --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. +.TP +.B \-C, --conf-file=<file> +Specify a different configuration file. The conf-file option is also allowed in +configuration files, to include multiple configuration files. +.TP +.B \-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. +.SH CONFIG FILE +At startup, dnsmasq reads +.I /etc/dnsmasq.conf, +if it exists. (On +FreeBSD, the file is +.I /usr/local/etc/dnsmasq.conf +) (but see the +.B \-C +and +.B \-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. +.SH NOTES +When it receives a SIGHUP, +.B dnsmasq +clears its cache and then re-loads +.I /etc/hosts +and +.I /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 +.B +--no-poll +is set SIGHUP also re-reads +.I /etc/resolv.conf. +SIGHUP +does NOT re-read the configuration file. +.PP +When it receives a SIGUSR1, +.B 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 +.B --no-daemon +mode or when full logging is enabled (-q), a complete dump of the +contents of the cache is made. +.PP +When it receives SIGUSR2 and it is logging direct to a file (see +.B --log-facility +) +.B 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 +.B create +and +.B delaycompress. + + +.PP +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 +.I /etc/resolv.conf +to discover the IP +addresses of the upstream nameservers it should use, since the +information is typically stored there. Unless +.B --no-poll +is used, +.B dnsmasq +checks the modification time of +.I /etc/resolv.conf +(or equivalent if +.B \--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 +.I /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 +.I /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 +.I /etc/ppp/resolv.conf +and +.I /etc/dhcpc/resolv.conf +and will use the contents of whichever changed +last, giving automatic switching between DNS servers. +.PP +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. +.PP +In order to configure dnsmasq to act as cache for the host on which it is running, put "nameserver 127.0.0.1" in +.I /etc/resolv.conf +to force local processes to send queries to +dnsmasq. Then either specify the upstream servers directly to dnsmasq +using +.B \--server +options or put their addresses real in another file, say +.I /etc/resolv.dnsmasq +and run dnsmasq with the +.B \-r /etc/resolv.dnsmasq +option. This second technique allows for dynamic update of the server +addresses by PPP or DHCP. +.PP +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. + +.PP +The network-id system works as follows: For each DHCP request, dnsmasq +collects a set of valid network-id tags, one from the +.B dhcp-range +used to allocate the address, one from any matching +.B dhcp-host +(and "known" if a dhcp-host matches) +the tag "bootp" for BOOTP requests, a tag whose name is the +name if the interface on which the request arrived, +and possibly many from matching vendor classes and user +classes sent by the DHCP client. Any +.B dhcp-option +which has network-id tags will be used in preference to an untagged +.B dhcp-option, +provided that _all_ the tags match somewhere in the +set collected as described above. The prefix '#' on a tag means 'not' +so --dhcp=option=#purple,3,1.2.3.4 sends the option when the +network-id tag purple is not in the set of valid tags. +.PP +If the network-id in a +.B dhcp-range +is prefixed with 'net:' then its meaning changes from setting a +tag to matching it. Thus if there is more than dhcp-range on a subnet, +and one is tagged with a network-id which is set (for instance +from a vendorclass option) then hosts which set the netid tag will be +allocated addresses in the tagged range. +.PP +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 +.B dhcp-host +configurations or in +.I /etc/ethers +, and a +.B 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 matched against netids in +.B dhcp-option +configurations, as is the tag "bootp", allowing some control over the options returned to +different classes of hosts. + +.SH EXIT CODES +.PP +0 - Dnsmasq successfully forked into the background, or terminated +normally if backgrounding is not enabled. +.PP +1 - A problem with configuration was detected. +.PP +2 - A problem with network access occurred (address in use, attempt +to use privileged ports without permission). +.PP +3 - A problem occurred with a filesystem operation (missing +file/directory, permissions). +.PP +4 - Memory allocation failure. +.PP +5 - Other miscellaneous problem. +.PP +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. + +.SH 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. + +.PP +Dnsmasq is capable of handling DNS and DHCP for at least a thousand +clients. Clearly to do this the value of +.B --dhcp-lease-max +must be increased, +and lease times should not be very short (less than one hour). The +value of +.B --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 +.B NOTES +section for details. + +.PP +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 +.B --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. + +.PP +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 +.B /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. + +.SH 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. + +.SH FILES +.IR /etc/dnsmasq.conf + +.IR /usr/local/etc/dnsmasq.conf + +.IR /etc/resolv.conf + +.IR /etc/hosts + +.IR /etc/ethers + +.IR /var/lib/misc/dnsmasq.leases + +.IR /var/db/dnsmasq.leases + +.IR /var/run/dnsmasq.pid +.SH SEE ALSO +.BR hosts (5), +.BR resolver (5) +.SH AUTHOR +This manual page was written by Simon Kelley <simon@thekelleys.org.uk>. + + |